jcc-express-mvc 1.9.2 → 1.9.4

package/final-documentation/Architecture Concept/Request-Lifecycle.md

@@ -0,0 +1,137 @@
+# Request lifecycle
+
+## Introduction
+
+When you use any tool in the real world, you work with more confidence when you understand how that tool works. Building applications is no different. When you know how your framework handles an HTTP request, you feel more comfortable choosing middleware, debugging routes, and structuring `app/` and `route/`.
+
+This document gives a high-level picture of how JCC Express MVC works: Express.js underneath, with a Laravel-inspired service container, HTTP kernel, service providers, and routing.
+
+---
+
+## Lifecycle overview
+
+At the highest level:
+
+```text
+Web server / reverse proxy
+    → Node runs server.ts
+    → bootstrap/app builds the Application (container + config + providers + kernel + middleware)
+    → app.run() loads routes into RouteBuilder, then listens on PORT
+    → Each request: Express middleware stack → kernel middleware → container binds req/res
+    → Router matches route → route middleware → controller or closure → response
+    → Response finishes; per-request container bindings are cleared
+```
+
+---
+
+## First steps
+
+### The entry point
+
+The entry point for the HTTP application is `server.ts` at the project root (not `public/index.php` like PHP Laravel—your reverse proxy forwards to the Node/Bun process). `server.ts` is small: it imports the application from `bootstrap/app` and calls `app.run()`.
+
+```typescript
+import { app } from "./bootstrap/app";
+app.run();
+```
+
+### Loading the application
+
+`bootstrap/app.ts` builds an `Application` instance through `Application.configuration()`—a builder that wires routing, `app/Config`, service providers, `app/Http/kernel`, and global middleware, then `.create()`. That returns the same `app` you import in `server.ts`.
+
+The first structural object the framework gives you is this Application: it acts as the service container (bind / resolve services) and wraps the Express app used for HTTP.
+
+---
+
+## HTTP kernel
+
+In Laravel, the HTTP kernel is `Illuminate\Foundation\Http\Kernel`. In JCC Express MVC, the equivalent is `app/Http/kernel.ts`: a class registered as `HttpKernel` whose `middlewares` array becomes part of the global Express pipeline.
+
+The kernel is the central place through which every web request passes after the framework’s own Express setup (body parsers, session, CORS, logging, rate limiting, `HttpRequest` / `HttpResponse`, etc.) and before your routes run.
+
+The kernel also declares `middlewareAliases`—short names like `auth`, `guest`, or throttles—that you attach per route with `Route.middleware(['auth'])`.
+
+Think of the stack as: framework defaults → your kernel `middlewares` (for example CSRF, method spoofing, Inertia) → route matching → route middleware → handler. The kernel’s job is to define that global slice and the alias map; the `Middleware` class inside `jcc-express-mvc` applies the full chain to Express when the app is built.
+
+---
+
+## Service providers
+
+One of the most important bootstrap steps is loading service providers. Providers register bindings on the container (`register`) and run extra setup once registrations exist (`boot`).
+
+In `ApplicationBuilder.withProviders()`, the framework prepends `DatabaseServiceProvider`, registers your list from `bootstrap/providers.ts` (and may place `AuthServiceProvider` early), then appends `QueueServiceProvider`. That order matters so the database, auth, and queue subsystems are available where other code expects them.
+
+Your own providers live under `app/Providers/` (for example `AppServiceProvider`) and are listed in `bootstrap/providers.ts`. Use `AppServiceProvider` (or additional providers) for container bindings, config-driven setup, and small bootstrap tasks—same idea as Laravel’s `AppServiceProvider`.
+
+Most “big” features (database, queues, routing registration, events) are tied to framework or app providers. Understanding register vs boot helps when something is “not bound yet” during startup.
+
+---
+
+## Routing
+
+After the application is built and `app.run()` executes:
+
+1. `RouteBuilder` receives the service container.
+2. `RouteServiceProvider.loadRoutes()` runs each configured route module (for example `route/web`, `route/api`) with the right URL prefix from `bootstrap/app.ts`. Route files call `Route.get`, `Route.post`, etc., which record routes in `RouteBuilder`—they do not yet attach to Express in all setups until the next step.
+3. `Server` opens `PORT`, then calls `RouteBuilder.registerRoute(expressApp)`, which registers method + path + middleware + handler on Express and wires global error handling.
+
+So: providers and kernel configure the app; route files declare endpoints; listening is when those endpoints are mounted on Express.
+
+When a request arrives, Express dispatches it to the matching route. The handler may be a closure or a controller method resolved from the container.
+
+---
+
+## Middleware
+
+Middleware filters or inspects the request (and sometimes the response path). Examples:
+
+- Global middleware—applied to every request—includes the framework stack (JSON, session, CORS, …) plus `Kernel.middlewares` (CSRF, Inertia, …).
+- Route middleware—only on routes that name it—uses `Kernel.middlewareAliases` (`auth`, `guest`, …).
+
+If the request fails a guard (for example user not authenticated), middleware can redirect or abort before your controller runs.
+
+If the request passes all matched middleware, your route or controller runs and produces the response (JSON, Blade, Inertia, redirect, …).
+
+Reference — framework middleware order (before kernel entries), from `jcc-express-mvc/lib/Middleware`:
+
+1. `express.json()`
+2. `express.urlencoded({ extended: false })`
+3. `cookie-parser()`
+4. `express-session`
+5. `connect-flash`
+6. `express-fileupload`
+7. CORS (`app.config.cors`)
+8. Morgan (format depends on `APP_DEBUG`)
+9. Rate limit (`app.config.rateLimit`)
+10. `HttpRequest` / `HttpResponse` and `jccSession` on `req`
+
+Then `Kernel.middlewares` runs in array order. After that, middleware binds `request`, `response`, and `next` on the container for helpers like `view()` and `inertia()`.
+
+Inertia: visits with the `X-Inertia` header receive a JSON page payload; full page loads get HTML from the root Blade view. The same route handler often serves both; Inertia middleware and `res.inertia` handle the difference.
+
+---
+
+## Finishing up
+
+When your controller or closure finishes—by calling `res.send`, `res.json`, `res.render`, `view()`, `res.inertia`, `inertia()`, `redirect()`, `res.inertiaRedirect()`, or returning a value the route wrapper turns into JSON—Express ends the response.
+
+The framework listens for `finish` on the response and clears the per-request `request` / `response` / `next` bindings on the container so the next request does not leak state.
+
+If an error is passed to `next(error)` or thrown without being caught, `AppErrorHandler` maps it to an HTTP response (status and body) according to framework rules.
+
+---
+
+## Focus on service providers
+
+Service providers are the main lever for bootstrapping a JCC Express MVC application: the Application is created, providers `register` and `boot`, routes are loaded and registered, then requests hit the kernel and router.
+
+Your `bootstrap/providers.ts` list is the counterpart to Laravel’s provider list—keep it focused: put general bindings in `AppServiceProvider`, and add more providers when a feature needs its own `register`/`boot` block.
+
+---
+
+## Where to customize (quick reference)
+
+- Global HTTP middleware — `app/Http/kernel.ts` → `middlewares` and `middlewareAliases`.
+- Default Express stack — `jcc-express-mvc/lib/Middleware` + `app/Config` (CORS, rate limit, engine).
+- Routes and API prefixes — `route/*.ts` and `bootstrap/app.ts` → `withRouting`.
+- Container bindings and boot logic — `app/Providers/*` and `bootstrap/providers.ts`.

package/final-documentation/Architecture Concept/Service-Container.md

@@ -0,0 +1,134 @@
+# Service container
+
+## Introduction
+
+The service container is a registry for creating and retrieving objects in your application. Instead of constructing dependencies by hand in every controller or route, you bind how something should be built once, then resolve it whenever you need it—similar in spirit to Laravel’s container.
+
+In JCC Express MVC, the `Application` class is the container: it extends `ExpressApplication`, which extends `Container` from `jcc-express-mvc`. When `bootstrap/app` finishes building, you have a single `app` object that is both the Express app owner and the dependency injection hub.
+
+---
+
+## Why use a container
+
+- One place to wire implementations (interfaces → concrete classes, factories, config).
+- Singletons for expensive or shared services (database, cache clients, queues).
+- Request-scoped values (`request`, `response`, `next`) registered per HTTP request and cleared when the response ends.
+- Constructor injection where `reflect-metadata` can resolve parameter types from the container (used in parts of the framework and advanced app code).
+
+---
+
+## Core API
+
+Bindings are keyed by string (for example `"TestingService"`) or by class / constructor name when using `make()` / `build()`.
+
+### `bind(abstract, concrete, shared?)`
+
+Registers how to build a service. `concrete` may be:
+
+- A class — instantiated with optional constructor injection.
+- A factory function `(container) => instance` — you control creation.
+
+If `shared` is `true`, the first resolved instance may be cached (singleton behavior for that binding).
+
+### `singleton(abstract, concrete)`
+
+Ensures a binding exists and marks it shared so `resolve` returns the same instance afterward (typical for app-wide services).
+
+### `instance(abstract, object)`
+
+Registers a ready-made object under a key. Used for:
+
+- `app.instance("app", this)` in `Application`’s constructor.
+- `app.instance("request", req)` / `response` / `next` during a request (see `Middleware` in `jcc-express-mvc`).
+
+### `resolve(abstract, parameters?, callFactory?)`
+
+Returns an instance: checks instances map, aliases, then bindings, and may `build` a class with injected dependencies.
+
+### `make(Class, params?)`
+
+Registers the class name if needed and `resolve`s it—handy for on-the-fly resolution.
+
+### `alias(alias, abstract)`
+
+Lets you `resolve` using an alternate name pointing at the same binding.
+
+### `has(abstract)`
+
+Returns whether a binding, instance, or alias exists.
+
+### `forget(abstract)` / `forgetMany(keys[])`
+
+Removes instances (and related alias keys). The framework uses `forgetMany(["request", "response", "next"])` after each response `finish` so the next request does not reuse stale `req`/`res`.
+
+---
+
+## Where bindings come from
+
+1. Framework constructor — `Application` registers `app`, `RouteServiceProvider`, `Event`, etc.
+2. `ExpressApplication` — Binds `express`, `expressApp`, `httpListen`, `socketIo`, etc.
+3. Service providers — In `register()`, call `this.app.bind(...)` / `singleton(...)`. See `app/Providers/AppServiceProvider.ts` and `bootstrap/providers.ts`.
+4. HTTP pipeline — Middleware puts `request`, `response`, `next` on the container for the current request.
+5. Your code — Anywhere you have `app`, you can bind services at startup or (less often) at runtime.
+
+---
+
+## Dependency injection on constructors
+
+`Container.build()` uses `reflect-metadata` (`design:paramtypes`) to guess constructor parameters and `resolve` them by type name. This works when:
+
+- `emitDecoratorMetadata` is enabled in `tsconfig.json` (your project has it).
+- Parameter types are classes or names the container knows.
+
+If resolution fails, you may need an explicit `bind` for that type or pass parameters into `resolve`.
+
+---
+
+## Controllers and `callControllerMethod`
+
+For controller actions, the framework can `callControllerMethod`, which reads `inject:method:deps` metadata and resolves FormRequest, models, route parameters, etc. Plain routes that use `(req, res) =>` do not need this—you still benefit from `view()` / `inertia()` because they read `response` from the container after it is bound.
+
+---
+
+## Global `app` and helpers
+
+After `globalHelpers(app)` runs (during `ApplicationBuilder.create()`), `globalThis.app` is the Application instance. Helpers like `env()`, `view()`, `inertia()` use the container under the hood (for example `response` from `app.resolve("response")`).
+
+Prefer constructor injection or explicit `app.resolve()` in providers and long-lived services; use globals where the framework already does (routes, Blade/Inertia helpers).
+
+---
+
+## Comparison to Laravel (mental model)
+
+- Container class — Laravel: `Illuminate\Container\Container`. JCC: `jcc-express-mvc/lib/Container`.
+- Application — Laravel’s `Application` extends the container. JCC: `Application` → `ExpressApplication` → `Container`.
+- Registering services — Laravel: `AppServiceProvider::register`. JCC: same idea in `app/Providers/*` → `register()`.
+- Resolving — Laravel: `app()`, `resolve()`. JCC: `app.resolve()`, `app.make()`.
+- Current HTTP request — Laravel: type-hint `Request`. JCC: `instance("request", req)` (and `response` / `next`) per request.
+
+---
+
+## Practical pattern in a provider
+
+```typescript
+// app/Providers/AppServiceProvider.ts (conceptual)
+import { ServiceProvider } from "jcc-express-mvc/Core/Provider";
+
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.singleton("MyApiClient", () => {
+      return new MyApiClient(env("API_URL") ?? "");
+    });
+  }
+
+  async boot(): Promise<void> {
+    // use other bindings, gates, events, …
+  }
+}
+```
+
+Elsewhere:
+
+```typescript
+const client = app.resolve<MyApiClient>("MyApiClient");
+```

package/final-documentation/Architecture Concept/Service-Provider.md

@@ -0,0 +1,105 @@
+# Service providers
+
+## Introduction
+
+Service providers are the main way to bootstrap features in JCC Express MVC. Each provider is a class that receives the `Application` (the service container) and uses `register()` to bind services and `boot()` to run logic after all providers have registered—mirroring Laravel’s register / boot split.
+
+Listing providers in `bootstrap/providers.ts` and implementing them under `app/Providers/` keeps startup explicit and ordered.
+
+---
+
+## What a provider does
+
+A provider connects the framework to your app:
+
+- Register container bindings (`bind`, `singleton`, `instance`) so other code can `resolve` them.
+- Boot behavior that depends on those bindings (routes are not registered here—`RouteServiceProvider` loads route files during `app.run()`, but your `boot()` can use `Gate`, events, or other services already on the container).
+
+The abstract base class lives in `jcc-express-mvc` (`ServiceProvider`). Extend it from `jcc-express-mvc/Core/Provider` (re-export) or the underlying `lib/Providers/ServiceProvider`.
+
+---
+
+## The `ServiceProvider` base class
+
+- `constructor(protected app: Application)` — Stores the application instance as `this.app`.
+- `abstract register(): void` — You must implement this. Put container registrations here only; avoid resolving services that other providers have not registered yet.
+- `boot(): void | Promise<void>` — Optional override. Runs after every provider’s `register()` has completed (see When `register` and `boot` run). Use for `Gate.define`, subscribing to events, or resolving bindings that need the full container.
+- `listen` / `subscribe` — Optional maps used when `bootListeners` or `bootSubscribers` is set on the provider so the `Application` wires event listeners or subscribers during registration.
+
+---
+
+## Registration order (`ApplicationBuilder`)
+
+In `withProviders()`, the builder does not use your array alone. It builds this chain:
+
+1. `DatabaseServiceProvider` — Always first (database-related setup).
+2. Your providers from `bootstrap/providers.ts` — If `AuthServiceProvider` (framework) is in the list but not first, the builder moves it to the front of your list so auth is set up early.
+3. `QueueServiceProvider` — Always last in the chain.
+
+That order matters when one provider’s `register()` assumes another binding already exists.
+
+---
+
+## When `register` and `boot` run
+
+During `bootstrap/app` build:
+
+- For each provider class in the chain, `new Provider(app)` is called, then `register()` runs immediately.
+- If the provider sets `bootSubscribers` / `bootListeners`, the app may call `subscribers()` / `listeners()` right after that provider registers.
+
+`boot()` for all providers:
+
+- When `app.boot()` runs (for example from `app.run()` if the app was not yet booted), the application loops `this.providers` and calls `boot()` on each in registration order.
+
+Late registration:
+
+- If a provider is registered after the application is already `booted`, `register()` still runs, and `bootProvider` is invoked immediately for that provider so it does not miss the boot phase.
+
+---
+
+## Writing a provider
+
+1. Create a class under `app/Providers/` extending `ServiceProvider`.
+2. Implement `register()` with `this.app.bind`, `singleton`, etc.
+3. Override `boot()` when you need work after all `register()` methods have finished.
+4. Add the class to the `providers` array exported from `bootstrap/providers.ts` (already imported by `bootstrap/app.ts` via `withProviders`).
+
+Keep `register()` free of heavy side effects and of `resolve()` calls that depend on providers later in the chain unless you know the order.
+
+---
+
+## Example
+
+```typescript
+// app/Providers/AppServiceProvider.ts
+import { ServiceProvider } from "jcc-express-mvc/Core/Provider";
+
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.singleton("Billing", () => new BillingService());
+  }
+
+  async boot(): Promise<void> {
+    const billing = this.app.resolve<BillingService>("Billing");
+    // configure billing from config, register policies, etc.
+  }
+}
+```
+
+```typescript
+// bootstrap/providers.ts
+import { AppServiceProvider } from "../app/Providers/AppServiceProvider";
+
+export const providers = [AppServiceProvider];
+```
+
+---
+
+## Framework providers you should know about
+
+- `DatabaseServiceProvider` — Database / ORM wiring; runs before your list.
+- `AuthServiceProvider` (when included) — Intended to run early among your providers.
+- `QueueServiceProvider` — Queue binding; runs after your list.
+- `RouteServiceProvider` — Not in your `bootstrap/providers.ts` list by default; it is registered as a singleton on `Application` and `loadRoutes()` is invoked from `app.run()` to load `route/web`, `route/api`, etc.
+
+Your `AppServiceProvider` (and any custom providers) are where application-specific bindings and `boot` logic belong.

package/final-documentation/Database/Database-Introduction.md

@@ -0,0 +1,240 @@
+# Database: Getting Started
+
+## Introduction
+
+Almost every real application needs a database. JCC Express MVC keeps this flexible by supporting:
+
+- **JCC ORM (default)** for SQL with a Knex-backed query layer
+- **Sequelize** as an alternative SQL ORM
+- **Mongoose** for MongoDB document workflows
+
+In practice, most projects start with the default JCC stack, then switch ORM mode only when needed.
+
+---
+
+## Supported database engines
+
+With the default JCC SQL path (`DB_ORM=jcc`), connection clients include:
+
+- `mysql2`
+- `postgres`
+- `sqlite`
+- `better-sqlite3`
+
+For document databases, use `DB_ORM=mongoose` with your Mongo connection settings.
+
+---
+
+## Configuration
+
+Database settings live in your app config and environment values:
+
+- `app/Config/database.ts`
+- `app/Config/index.ts` (exports `database`)
+- `.env` values such as `DB_ORM`, `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`
+
+Minimal shape from `app/Config/database.ts`:
+
+```typescript
+export const database = {
+  orm: config.get("DB_ORM", "jcc"),
+  sequelize: { /* ... */ },
+  mongoose: { /* ... */ },
+};
+```
+
+---
+
+## SQLite configuration
+
+For SQLite style connections (`sqlite` or `better-sqlite3`), the default JCC database layer resolves to a file database (`db.sqlite`) at project root.
+
+Typical env setup:
+
+```env
+DB_ORM=jcc
+DB_CONNECTION=sqlite
+DB_DATABASE=db.sqlite
+```
+
+If you need a different file location, align your adapter/config with your deployment path strategy.
+
+---
+
+## Choosing ORM mode
+
+The provider layer uses your env/config to decide connection behavior:
+
+- `DB_ORM=jcc` -> JCC/Knex SQL flow
+- `DB_ORM=sequelize` -> Sequelize connection path
+- `DB_ORM=mongoose` -> Mongoose connection path
+
+Keep `DB_ORM` and `DB_CONNECTION` consistent (for example, do not pair `DB_ORM=mongoose` with SQL-only assumptions in your app code).
+
+---
+
+## Running queries
+
+### Query builder style
+
+```typescript
+const users = await DB.table("users").get();
+const user = await DB.table("users").where("id", 1).first();
+```
+
+### Raw SQL
+
+```typescript
+const rows = await DB.runQuery("select * from users where active = ?", [1]);
+```
+
+Or:
+
+```typescript
+const raw = DB.raw("select count(*) as total from users");
+```
+
+Use bound parameters (`?`) instead of string interpolation to reduce SQL injection risk.
+
+---
+
+## More method usage examples
+
+### Inserts
+
+```typescript
+await DB.table("users").insert({
+  name: "Abdou",
+  email: "abdou@example.com",
+});
+```
+
+### Updates
+
+```typescript
+await DB.table("users").where("id", 1).update({
+  name: "Abdou J",
+});
+```
+
+### Deletes
+
+```typescript
+await DB.table("users").where("id", 1).delete();
+```
+
+### Filtering and ordering
+
+```typescript
+const activeUsers = await DB.table("users")
+  .where("active", true)
+  .orderBy("created_at", "desc")
+  .limit(20)
+  .get();
+```
+
+### Column selection
+
+```typescript
+const slim = await DB.table("users")
+  .select("id", "name", "email")
+  .where("active", true)
+  .get();
+```
+
+### Counting and aggregates
+
+```typescript
+const totalUsers = await DB.table("users").count("id as total");
+const maxScore = await DB.table("users").max("score as max_score");
+const avgScore = await DB.table("users").avg("score as avg_score");
+```
+
+### Pagination (offset/limit style)
+
+```typescript
+const page = 2;
+const perPage = 15;
+
+const rows = await DB.table("users")
+  .offset((page - 1) * perPage)
+  .limit(perPage)
+  .get();
+```
+
+### Conditional create/update patterns
+
+```typescript
+const exists = await DB.table("users").where("email", email).exists();
+
+if (!exists) {
+  await DB.table("users").insert({ email, name });
+} else {
+  await DB.table("users").where("email", email).update({ name });
+}
+```
+
+### Raw expression inside builder
+
+```typescript
+const report = await DB.table("orders")
+  .select("status")
+  .select(DB.raw("count(*) as total"))
+  .groupBy("status")
+  .get();
+```
+
+---
+
+## Transactions
+
+JCC DB supports transaction wrappers:
+
+```typescript
+await DB.transaction(async () => {
+  await DB.table("users").insert({ name: "Abdou" });
+  await DB.table("profiles").insert({ user_id: 1 });
+});
+```
+
+Keep schema-altering or implicit-commit statements out of transactional write flows unless you fully understand your database engine behavior.
+
+---
+
+## Migrations and seeders
+
+Use ArtisanNode for schema and seed lifecycle:
+
+```bash
+bun artisanNode make:migration create_users_table
+bun artisanNode migrate
+bun artisanNode migrate:rollback
+bun artisanNode migrate:reset
+bun artisanNode migrate:fresh
+bun artisanNode db:seed
+bun artisanNode db:wipe
+```
+
+Queue tables:
+
+```bash
+bun artisanNode make:queue-table
+bun artisanNode migrate
+```
+
+---
+
+## Practical recommendations
+
+- Start with the default JCC stack unless a project requirement mandates Sequelize or Mongoose.
+- Keep migrations in version control and run them in CI/CD.
+- Prefer parameterized queries over manual string building.
+- Validate production env values (`DB_ORM`, credentials, host/port) early in deployment.
+
+---
+
+## Summary
+
+- JCC gives you one database entry point with multiple ORM backends.
+- Config is env-driven and centered in `app/Config/database.ts`.
+- Use `DB.table(...)`, `DB.runQuery(...)`, and migrations/seeders for day-to-day database work.