npm - @nitronjs/framework - Versions diffs - 0.2.27 → 0.3.0 - Mend

@nitronjs/framework 0.2.27 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

package/README.md +260 -170
package/lib/Auth/Auth.js +2 -2
package/lib/Build/CssBuilder.js +5 -7
package/lib/Build/EffectivePropUsage.js +174 -0
package/lib/Build/FactoryTransform.js +1 -21
package/lib/Build/FileAnalyzer.js +1 -32
package/lib/Build/Manager.js +354 -58
package/lib/Build/PropUsageAnalyzer.js +1189 -0
package/lib/Build/jsxRuntime.js +25 -155
package/lib/Build/plugins.js +212 -146
package/lib/Build/propUtils.js +70 -0
package/lib/Console/Commands/DevCommand.js +30 -10
package/lib/Console/Commands/MakeCommand.js +8 -1
package/lib/Console/Output.js +0 -2
package/lib/Console/Stubs/rsc-consumer.tsx +74 -0
package/lib/Console/Stubs/vendor-dev.tsx +30 -41
package/lib/Console/Stubs/vendor.tsx +25 -1
package/lib/Core/Config.js +0 -6
package/lib/Core/Paths.js +0 -19
package/lib/Database/Migration/Checksum.js +0 -3
package/lib/Database/Migration/MigrationRepository.js +0 -8
package/lib/Database/Migration/MigrationRunner.js +1 -2
package/lib/Database/Model.js +19 -11
package/lib/Database/QueryBuilder.js +25 -4
package/lib/Database/Schema/Blueprint.js +10 -0
package/lib/Database/Schema/Manager.js +2 -0
package/lib/Date/DateTime.js +1 -1
package/lib/Dev/DevContext.js +44 -0
package/lib/Dev/DevErrorPage.js +990 -0
package/lib/Dev/DevIndicator.js +836 -0
package/lib/HMR/Server.js +16 -37
package/lib/Http/Server.js +171 -23
package/lib/Logging/Log.js +34 -2
package/lib/Mail/Mail.js +41 -10
package/lib/Route/Router.js +43 -19
package/lib/Runtime/Entry.js +10 -6
package/lib/Session/Manager.js +103 -1
package/lib/Session/Session.js +0 -4
package/lib/Support/Str.js +6 -4
package/lib/Translation/Lang.js +376 -32
package/lib/Translation/pluralize.js +81 -0
package/lib/Validation/MagicBytes.js +120 -0
package/lib/Validation/Validator.js +46 -29
package/lib/View/Client/hmr-client.js +100 -90
package/lib/View/Client/spa.js +121 -50
package/lib/View/ClientManifest.js +60 -0
package/lib/View/FlightRenderer.js +100 -0
package/lib/View/Layout.js +0 -3
package/lib/View/PropFilter.js +81 -0
package/lib/View/View.js +230 -495
package/lib/index.d.ts +22 -1
package/package.json +2 -2
package/skeleton/config/app.js +1 -0
package/skeleton/config/server.js +13 -0
package/skeleton/config/session.js +3 -0
package/lib/Build/HydrationBuilder.js +0 -190
package/lib/Console/Stubs/page-hydration-dev.tsx +0 -72
package/lib/Console/Stubs/page-hydration.tsx +0 -53

package/README.md CHANGED Viewed

@@ -1,39 +1,49 @@
-# NitronJS
+<p align="center">
+  <h1 align="center">NitronJS</h1>
+</p>
-A modern full-stack Node.js framework with React Server Components, Islands Architecture, and built-in tooling. Built on React and Fastify for high performance and developer productivity.
+<p align="center">
+  A full-stack MVC framework built on Fastify and React Server Components.<br/>
+  Build production-ready Node.js applications with a built-in ORM, authentication, mail, validation, and instant HMR.
+</p>
-## Why NitronJS?
+<p align="center">
+  <a href="https://www.npmjs.com/package/@nitronjs/framework"><img src="https://img.shields.io/npm/v/@nitronjs/framework.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@nitronjs/framework"><img src="https://img.shields.io/npm/l/@nitronjs/framework.svg" alt="license"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@nitronjs/framework.svg" alt="node version"></a>
+</p>
-- **Zero Config** - Start building immediately. No webpack, no babel config, no boilerplate
-- **Server Components by Default** - All components render on the server. Add `"use client"` only where needed
-- **Islands Architecture** - Client components hydrate independently, keeping your pages fast
-- **Instant HMR** - Changes reflect immediately without losing state
-- **Full-Stack** - Database ORM, authentication, sessions, validation all built-in
+<p align="center">
+  <b>NitronJS is currently under active development. APIs may change before the stable release.</b>
+</p>
-## Installation
+---
+## Quick Start
 ```bash
 npx -y @nitronjs/framework my-app
 cd my-app
+npm run storage:link
 npm run dev
 ```
-> **Note:** The `-y` flag skips npm's confirmation prompt for a smoother experience.
 Your app will be running at `http://localhost:3000`
+---
 ## Core Concepts
 ### Server Components (Default)
-Every `.tsx` file in `resources/views/` is a Server Component by default. They run on the server, have full access to your database, file system, and never ship JavaScript to the browser.
+Every `.tsx` file in `resources/views/` is a Server Component by default. They run on the server and have full access to your database and file system.
 ```tsx
 // resources/views/Site/Home.tsx
-import User from '@/app/Models/User.js';
+import User from '@models/User';
 export default async function Home() {
-    const users = await User.get(); // Direct database access
+    const users = await User.get();
     return (
         <div>
@@ -53,7 +63,6 @@ export default async function Home() {
 Add `"use client"` at the top of a file to make it interactive. These components hydrate on the browser and can use React hooks.
 ```tsx
-// resources/views/Components/Counter.tsx
 "use client";
 import { useState } from 'react';
@@ -68,25 +77,9 @@ export default function Counter() {
 }
 ```
-Use client components inside server components:
-```tsx
-// resources/views/Site/Home.tsx (Server Component)
-import Counter from '../Components/Counter';
-export default function Home() {
-    return (
-        <div>
-            <h1>Welcome</h1>
-            <Counter /> {/* Hydrates as an island */}
-        </div>
-    );
-}
-```
 ### Layouts
-Create `Layout.tsx` files to wrap pages. Layouts are discovered automatically by walking up the directory tree.
+Create `Layout.tsx` files to wrap pages. Layouts are discovered automatically by walking up the directory tree. During SPA navigation, layouts persist and only page content is updated — no full page reloads.
 ```
 resources/views/
@@ -98,53 +91,14 @@ resources/views/
     └── Dashboard.tsx      # Uses both layouts
 ```
-```tsx
-// resources/views/Layout.tsx
-export default function RootLayout({ children }) {
-    return (
-        <html lang="en">
-            <head>
-                <meta charSet="UTF-8" />
-                <title>My App</title>
-            </head>
-            <body>
-                {children}
-            </body>
-        </html>
-    );
-}
-```
-```tsx
-// resources/views/Admin/Layout.tsx
-export default function AdminLayout({ children }) {
-    return (
-        <div className="admin-wrapper">
-            <nav>Admin Navigation</nav>
-            <main>{children}</main>
-        </div>
-    );
-}
-```
-Disable layout for a specific page:
-```tsx
-export const layout = false;
-export default function FullscreenPage() {
-    return <div>No layout wrapper</div>;
-}
-```
-## Routing
+### Routing
 Define routes in `routes/web.js`:
 ```javascript
 import { Route } from '@nitronjs/framework';
-import HomeController from '#app/Controllers/HomeController.js';
-import UserController from '#app/Controllers/UserController.js';
+import HomeController from '../app/Controllers/HomeController.js';
+import UserController from '../app/Controllers/UserController.js';
 // Basic routes
 Route.get('/', HomeController.index).name('home');
@@ -153,33 +107,60 @@ Route.get('/about', HomeController.about).name('about');
 // Route parameters
 Route.get('/users/:id', UserController.show).name('user.show');
-// Route groups with middleware
-Route.prefix('/admin').middleware('auth').group(() => {
-    Route.get('/dashboard', AdminController.dashboard).name('admin.dashboard');
-    Route.get('/users', AdminController.users).name('admin.users');
+// RESTful routes
+Route.post('/users', UserController.store).name('user.store');
+Route.put('/users/:id', UserController.update).name('user.update');
+Route.delete('/users/:id', UserController.destroy).name('user.destroy');
+// Route groups with prefix, name prefix, and middleware
+Route.prefix('/admin').name('admin.').middleware('auth').group(() => {
+    Route.get('/', DashboardController.index).name('dashboard');
+    Route.get('/users', AdminUserController.index).name('users');
+    // Nested groups
+    Route.prefix('/pages').name('pages.').group(() => {
+        Route.get('/:id/edit', PagesController.edit).name('edit');
+    });
 });
-// RESTful routes
-Route.post('/users', UserController.store);
-Route.put('/users/:id', UserController.update);
-Route.delete('/users/:id', UserController.destroy);
+// Middleware-only groups
+Route.middleware('guest').group(() => {
+    Route.get('/login', AuthController.getLogin).name('login');
+    Route.post('/login', AuthController.postLogin);
+});
 ```
-Generate URLs using route names:
+#### URL Generation
-```tsx
-<a href={route('user.show', { id: 1 })}>View User</a>
+The global `route()` function is available everywhere — controllers, views, and client-side code:
+```javascript
+// Basic
+route('home')                                        // => "/"
+// With parameters
+route('user.show', { id: 1 })                        // => "/users/1"
+// With query string
+route('admin.users', {}, { page: 2, q: 'search' })   // => "/admin/users?page=2&q=search"
+// Parameters + query string
+route('admin.pages.edit', { id: 5 }, { tab: 'seo' }) // => "/admin/pages/5/edit?tab=seo"
 ```
-## Controllers
+### Controllers
 ```javascript
 // app/Controllers/UserController.js
+import User from '../Models/User.js';
 class UserController {
     static async index(req, res) {
         const users = await User.get();
-        return res.view('User/Index', { users });
+        return res.view('User/Index', {
+            users
+        });
     }
     static async show(req, res) {
@@ -189,7 +170,9 @@ class UserController {
             return res.status(404).view('Errors/NotFound');
         }
-        return res.view('User/Show', { user });
+        return res.view('User/Show', {
+            user
+        });
     }
     static async store(req, res) {
@@ -207,12 +190,28 @@ class UserController {
 export default UserController;
 ```
-## Database
+### Path Aliases
+NitronJS provides built-in path aliases for clean imports in `.tsx` view files:
+| Alias | Path |
+|---|---|
+| `@models/*` | `app/Models/*` |
+| `@controllers/*` | `app/Controllers/*` |
+| `@middlewares/*` | `app/Middlewares/*` |
+| `@views/*` | `resources/views/*` |
+| `@css/*` | `resources/css/*` |
+| `@/*` | Project root |
+---
-### Models
+## Features
+### Database
+#### Models
 ```javascript
-// app/Models/User.js
 import { Model } from '@nitronjs/framework';
 export default class User extends Model {
@@ -220,30 +219,25 @@ export default class User extends Model {
 }
 ```
-### Queries
+#### Queries
 ```javascript
-// Find all
 const users = await User.get();
-// Find by ID
 const user = await User.find(1);
-// Where clauses
 const admins = await User.where('role', '=', 'admin').get();
-const active = await User.where('active', true).get();
-// Chaining
 const results = await User
-    .where('role', '=', 'admin')
     .where('active', true)
     .orderBy('created_at', 'desc')
     .limit(10)
     .get();
-// First result
 const user = await User.where('email', '=', 'john@example.com').first();
+// Aggregates
+const total = await User.count();
+const maxAge = await User.max('age');
 // Create
 const user = new User();
 user.name = 'John';
@@ -257,59 +251,58 @@ await User.where('id', '=', 1).update({ name: 'Jane' });
 await User.where('id', '=', 1).delete();
 ```
-### Migrations
+#### Migrations
 ```bash
-npm run make:migration create_users_table
+npm run make:migration create_posts_table
 ```
 ```javascript
-// database/migrations/2024_01_01_000000_create_users_table.js
 import { Schema } from '@nitronjs/framework';
-class CreateUsersTable {
+class CreatePostsTable {
     static async up() {
-        await Schema.create('users', (table) => {
+        await Schema.create('posts', (table) => {
             table.id();
-            table.string('name');
-            table.string('email').unique();
-            table.string('password');
+            table.string('title');
+            table.text('body');
+            table.string('slug').unique();
+            table.boolean('published').default(false);
+            table.json('metadata').nullable();
             table.timestamp('created_at');
             table.timestamp('updated_at').nullable();
         });
     }
     static async down() {
-        await Schema.dropIfExists('users');
+        await Schema.dropIfExists('posts');
     }
 }
-export default CreateUsersTable;
+export default CreatePostsTable;
 ```
-Run migrations:
 ```bash
 npm run migrate              # Run pending migrations
 npm run migrate:fresh        # Drop all tables and re-run
-npm run migrate:fresh --seed # Drop, migrate, and seed
+npm run migrate:fresh:seed   # Drop, migrate, and seed
+npm run migrate:rollback     # Rollback last batch
+npm run migrate:status       # Show migration status
 ```
-## Authentication
+### Authentication
 ```javascript
-// In a controller or middleware
 class AuthController {
     static async login(req, res) {
         const { email, password } = req.body;
         const success = await req.auth.attempt({ email, password });
         if (success) {
-            return req.redirect('/dashboard');
+            return res.redirect(route('dashboard'));
         }
-        return req.view('Auth/Login', {
+        return res.view('Auth/Login', {
             error: 'Invalid credentials'
         });
     }
@@ -317,7 +310,7 @@ class AuthController {
     static async logout(req, res) {
         await req.auth.logout();
-        return res.redirect('/');
+        return res.redirect(route('home'));
     }
 }
@@ -325,32 +318,26 @@ class AuthController {
 if (req.auth.check()) {
     const user = await req.auth.user();
 }
+// Named guards
+req.auth.guard('admin').check();
 ```
-## Session
+### Sessions
 ```javascript
-// Set value
 req.session.set('key', 'value');
-// Get value
 const value = req.session.get('key');
-// Flash messages (one-time)
+// Flash messages
 req.session.flash('success', 'Profile updated!');
 const message = req.session.getFlash('success');
-// All data
-const data = req.session.all();
-// Regenerate session ID (after login)
+// Regenerate session ID
 req.session.regenerate();
-// CSRF token
-const token = req.session.getCsrfToken();
 ```
-## Validation
+### Validation
 ```javascript
 import { Validator } from '@nitronjs/framework';
@@ -358,8 +345,9 @@ import { Validator } from '@nitronjs/framework';
 const validation = Validator.make(req.body, {
     name: 'required|string|min:2|max:100',
     email: 'required|email',
-    password: 'required|string|min:8',
-    age: 'numeric|min:18'
+    password: 'required|string|min:8|confirmed',
+    age: 'numeric|min:18',
+    avatar: 'file|mimes:png,jpg|max:2097152'
 });
 if (validation.fails()) {
@@ -369,9 +357,7 @@ if (validation.fails()) {
 }
 ```
-## Middleware
-Create custom middleware:
+### Middleware
 ```javascript
 // app/Middlewares/CheckAge.js
@@ -380,7 +366,6 @@ class CheckAge {
         if (req.query.age < 18) {
             return res.status(403).send('Access denied');
         }
-        // No return = continue to next handler
     }
 }
@@ -393,34 +378,114 @@ Register in `app/Kernel.js`:
 export default {
     routeMiddlewares: {
         'check-age': CheckAge,
-        'auth': AuthMiddleware,
+        'auth': AuthMiddleware
     }
 };
 ```
-Apply to routes:
+### Mail
 ```javascript
-Route.middleware('check-age').get('/restricted', Controller.method);
-Route.middleware('auth', 'check-age').get('/admin', AdminController.index);
+import { Mail } from '@nitronjs/framework';
+await Mail.from('noreply@app.com')
+    .to('user@email.com')
+    .subject('Welcome!')
+    .html('<h1>Hello</h1>')
+    .attachment({ filename: 'file.pdf', path: '/path/to/file.pdf' })
+    .send();
+// Using a template
+await Mail.to('user@email.com')
+    .view('emails/welcome', { name: 'Alice' })
+    .send();
 ```
-## CSS & Tailwind
+### Storage
-Put your CSS files in `resources/css/`. Tailwind CSS is automatically detected and processed.
+```javascript
+import { Storage } from '@nitronjs/framework';
+await Storage.put(file, 'upload_files', 'image.jpg');
+const buffer = await Storage.get('upload_files/image.jpg');
+await Storage.delete('upload_files/old.jpg');
+await Storage.move('upload_files/a.jpg', 'upload_files/b.jpg');
+Storage.exists('upload_files/image.jpg');
+Storage.url('upload_files/image.jpg');  // => "/storage/upload_files/image.jpg"
+```
-```css
-/* resources/css/app.css */
-@import "tailwindcss";
+### Encryption
+```javascript
+import { AES } from '@nitronjs/framework';
+const token = AES.encrypt({ userId: 1, expires: '2025-12-31' });
+const data = AES.decrypt(token);  // Returns false on tamper
 ```
-CSS files are automatically linked in your views:
+### Hashing
-```tsx
-// CSS from resources/css/ is available at /storage/css/
-<link rel="stylesheet" href="/storage/css/app.css" />
+```javascript
+import { Hash } from '@nitronjs/framework';
+const hashed = await Hash.make('password123');
+const valid = await Hash.check('password123', hashed);
+```
+### Logging
+```javascript
+import { Log } from '@nitronjs/framework';
+Log.info('User registered', { userId: 1 });
+Log.error('Payment failed', { orderId: 123 });
+Log.debug('Query executed', { sql: '...' });
+```
+### DateTime
+```javascript
+import { DateTime } from '@nitronjs/framework';
+DateTime.toSQL();                    // "2025-01-15 10:30:00"
+DateTime.getDate(timestamp, 'Y-m-d H:i:s');
+DateTime.addDays(7);
+DateTime.subHours(2);
 ```
+### Faker
+Built-in fake data generator for seeders and testing:
+```javascript
+import { Faker } from '@nitronjs/framework';
+Faker.fullName();       // "John Smith"
+Faker.email();          // "john@example.com"
+Faker.sentence();       // "Lorem ipsum dolor sit amet."
+Faker.int(1, 100);      // 42
+Faker.boolean();        // true
+Faker.uuid();           // "550e8400-e29b-41d4-a716-446655440000"
+Faker.creditCard();     // Luhn-valid card number
+Faker.hexColor();       // "#a3f29c"
+Faker.oneOf(['a', 'b', 'c']);
+```
+### String Utilities
+```javascript
+import { Str } from '@nitronjs/framework';
+Str.slug('Hello World');       // "hello-world"
+Str.camel('user_name');        // "userName"
+Str.pascal('user_name');       // "UserName"
+Str.snake('userName');         // "user_name"
+Str.random(32);                // Random string
+Str.limit('Long text...', 10); // "Long text..."
+```
+---
 ## CLI Commands
 ```bash
@@ -432,6 +497,9 @@ npm run start            # Start production server
 # Database
 npm run migrate          # Run migrations
 npm run migrate:fresh    # Fresh migration
+npm run migrate:fresh:seed # Fresh migration + seed
+npm run migrate:rollback # Rollback last batch
+npm run migrate:status   # Show migration status
 npm run seed             # Run seeders
 # Code Generation
@@ -445,31 +513,55 @@ npm run make:seeder <name>
 npm run storage:link     # Create storage symlink
 ```
+---
 ## Project Structure
 ```
 my-app/
 ├── app/
-│   ├── Controllers/     # Request handlers
-│   ├── Middlewares/     # Custom middleware
-│   └── Models/          # Database models
-├── config/              # Configuration files
+│   ├── Controllers/      # Request handlers
+│   ├── Middlewares/       # Custom middleware
+│   └── Models/            # Database models
+├── config/                # Configuration files
 │   ├── app.js
+│   ├── auth.js
 │   ├── database.js
-│   └── server.js
+│   ├── hash.js
+│   ├── server.js
+│   └── session.js
 ├── database/
-│   ├── migrations/      # Database migrations
-│   └── seeders/         # Database seeders
-├── public/              # Static assets
+│   ├── migrations/        # Database migrations
+│   └── seeders/           # Database seeders
+├── public/                # Static assets
 ├── resources/
-│   ├── css/             # Stylesheets
-│   └── views/           # React components (TSX)
+│   ├── css/               # Stylesheets
+│   └── views/             # React components (TSX)
 ├── routes/
-│   └── web.js           # Route definitions
-├── storage/             # File storage
-└── .env                 # Environment variables
+│   └── web.js             # Route definitions
+├── storage/               # File storage
+└── .env                   # Environment variables
 ```
+---
+## CSS & Tailwind
+Put your CSS files in `resources/css/`. Tailwind CSS v4 is automatically detected and processed.
+```css
+/* resources/css/global.css */
+@import "tailwindcss";
+```
+Import in your `.tsx` files using the `@css` alias:
+```tsx
+import "@css/global.css";
+```
+---
 ## Configuration
 Access configuration values:
@@ -478,7 +570,7 @@ Access configuration values:
 import { Config } from '@nitronjs/framework';
 const appName = Config.get('app.name');
-const dbHost = Config.get('database.host', 'localhost'); // with default
+const dbHost = Config.get('database.host', 'localhost');
 ```
 Environment variables in `.env`:
@@ -495,15 +587,13 @@ DATABASE_USERNAME=root
 DATABASE_PASSWORD=
 ```
+---
 ## Requirements
 - Node.js 18+
 - MySQL 5.7+ or MariaDB 10.3+
-## Documentation
-Full documentation available at [nitronjs.dev](https://nitronjs.dev/docs)
 ## License
 ISC