jcc-express-mvc 1.9.6 → 1.9.8

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

@@ -59,7 +59,7 @@ Think of the stack as: framework defaults → your kernel `middlewares` (for exa
 
 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.
+During application bootstrap, 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`.
 
@@ -92,7 +92,7 @@ If the request fails a guard (for example user not authenticated), middleware ca
 
 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`:
+Reference — default framework middleware order (before kernel entries):
 
 1. `express.json()`
 2. `express.urlencoded({ extended: false })`
@@ -117,7 +117,7 @@ When your controller or closure finishes—by calling `res.send`, `res.json`, `r
 
 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.
+If an error is passed to `next(error)` or thrown without being caught, the framework error handler maps it to an HTTP response (status and body). See [Error handling](../The%20Basics/Error-handling.md).
 
 ---
 
@@ -132,6 +132,6 @@ Your `bootstrap/providers.ts` list is the counterpart to Laravel’s provider li
 ## 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).
+- Default Express stack — framework global 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

@@ -84,15 +84,15 @@ If resolution fails, you may need an explicit `bind` for that type or pass param
 
 ---
 
-## Controllers and `callControllerMethod`
+## Controllers and method injection
 
-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.
+For controller actions, the framework resolves method parameters from container metadata: FormRequest classes, models, route parameters, and services. 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")`).
+After the application boots, `globalThis.app` is the Application instance. Helpers like `env()`, `view()`, and `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).
 
@@ -100,7 +100,7 @@ Prefer constructor injection or explicit `app.resolve()` in providers and long-l
 
 ## Comparison to Laravel (mental model)
 
-- Container class — Laravel: `Illuminate\Container\Container`. JCC: `jcc-express-mvc/lib/Container`.
+- Container — Laravel: `Illuminate\Container\Container`. JCC: the framework service container (resolved via `app.resolve()` / `app.make()`).
 - 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()`.

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

@@ -15,7 +15,7 @@ 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 abstract base class is **`ServiceProvider`**. Extend it from `jcc-express-mvc/Core/Provider`.
 
 ---
 
@@ -28,13 +28,17 @@ The abstract base class lives in `jcc-express-mvc` (`ServiceProvider`). Extend i
 
 ---
 
-## Registration order (`ApplicationBuilder`)
+## Registration order (bootstrap)
 
-In `withProviders()`, the builder does not use your array alone. It builds this chain:
+During `withProviders()`, the application 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.
+1. `LogServiceProvider`
+2. `DatabaseServiceProvider` — Knex / Sequelize / Mongoose setup (skipped when `DB_ORM=prisma` or `DB_ORM=typeorm`).
+3. `PrismaServiceProvider` — Prisma client singleton and graceful `$disconnect` (when configured).
+4. `TypeORMServiceProvider` — TypeORM `DataSource` singleton and graceful shutdown (when configured).
+5. `SessionServiceProvider`, `CacheServiceProvider`
+6. 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.
+7. `QueueServiceProvider` — Always last in the chain.
 
 That order matters when one provider’s `register()` assumes another binding already exists.
 
@@ -98,6 +102,8 @@ export const providers = [AppServiceProvider];
 ## Framework providers you should know about
 
 - `DatabaseServiceProvider` — Database / ORM wiring; runs before your list.
+- `PrismaServiceProvider` — Registers `database.prisma.service` when configured.
+- `TypeORMServiceProvider` — Registers `database.typeorm.dataSource` when configured.
 - `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.

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

@@ -7,6 +7,8 @@ Almost every real application needs a database. JCC Express MVC keeps this flexi
 - **JCC ORM (default)** for SQL with a Knex-backed query layer
 - **Sequelize** as an alternative SQL ORM
 - **Mongoose** for MongoDB document workflows
+- **Prisma** for schema-first SQL with generated client and migrations
+- **TypeORM** for decorator-based entities and `DataSource` repositories
 
 In practice, most projects start with the default JCC stack, then switch ORM mode only when needed.
 
@@ -23,6 +25,10 @@ With the default JCC SQL path (`DB_ORM=jcc`), connection clients include:
 
 For document databases, use `DB_ORM=mongoose` with your Mongo connection settings.
 
+For Prisma, use `DB_ORM=prisma` and configure `DATABASE_URL` plus `database.prisma.service` — see [Prisma](./Prisma.md).
+
+For TypeORM, use `DB_ORM=typeorm` and configure `database.typeorm.dataSource` — see [TypeORM](./TypeORM.md).
+
 ---
 
 ## Configuration
@@ -38,11 +44,15 @@ Minimal shape from `app/Config/database.ts`:
 ```typescript
 export const database = {
   orm: config.get("DB_ORM", "jcc"),
+  prisma: { service: PrismaService },
+  typeorm: { dataSource: TypeORMDataSource },
   sequelize: { /* ... */ },
   mongoose: { /* ... */ },
 };
 ```
 
+See [Prisma](./Prisma.md) and [TypeORM](./TypeORM.md) for full setup.
+
 ---
 
 ## SQLite configuration
@@ -68,6 +78,8 @@ 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
+- `DB_ORM=prisma` -> Prisma client path (see [Prisma](./Prisma.md))
+- `DB_ORM=typeorm` -> TypeORM DataSource path (see [TypeORM](./TypeORM.md))
 
 Keep `DB_ORM` and `DB_CONNECTION` consistent (for example, do not pair `DB_ORM=mongoose` with SQL-only assumptions in your app code).
 

package/final-documentation/Database/Migrations.md

@@ -135,12 +135,7 @@ Common schema helpers seen in the current codebase:
 
 ---
 
-## Full migration API (current source)
-
-This list is taken from the current implementation in:
-
-- `jcc-express-mvc/lib/Jcc-eloquent/lib/Schema/index.ts`
-- `jcc-express-mvc/lib/Jcc-eloquent/lib/Schema/BluePrint/index.ts`
+## Full migration API
 
 ### `Schema` methods
 

package/final-documentation/Database/Prisma.md

@@ -0,0 +1,278 @@
+# Prisma
+
+## Introduction
+
+JCC Express MVC supports [Prisma](https://www.prisma.io/) as an ORM option via `DB_ORM=prisma`. Prisma uses its own schema (`prisma/schema.prisma`), migrations, and generated client — separate from JCC Eloquent models in `app/Models/`.
+
+You can also use Prisma **alongside** JCC Eloquent by keeping `DB_ORM=jcc` and configuring `database.prisma.service` in `app/Config/database.ts` (the framework still registers a singleton Prisma client).
+
+---
+
+## Enable Prisma
+
+### Option A — Prisma as primary ORM
+
+```env
+DB_ORM=prisma
+
+DATABASE_URL="mysql://root:password@127.0.0.1:3306/your_database"
+DATABASE_HOST=127.0.0.1
+DATABASE_PORT=3306
+DATABASE_USER=root
+DATABASE_PASSWORD=password
+DATABASE_NAME=your_database
+```
+
+`DATABASE_URL` is used by the Prisma CLI (`prisma.config.ts`). **The framework does not pick a default runtime adapter.** You must configure one explicitly (see below).
+
+Built-in adapter factories (install the matching package when using `PRISMA_ADAPTER` or `database.prisma.adapter`):
+
+| `PRISMA_ADAPTER` | Package                                             |
+| ---------------- | --------------------------------------------------- |
+| `mariadb`        | `@prisma/adapter-mariadb`                           |
+| `postgres`       | `@prisma/adapter-pg` + `pg`                         |
+| `sqlite`         | `@prisma/adapter-better-sqlite3` + `better-sqlite3` |
+| `libsql`         | `@prisma/adapter-libsql`                            |
+
+```env
+PRISMA_ADAPTER=mariadb
+DATABASE_URL="mysql://root:password@127.0.0.1:3306/your_database"
+```
+
+Or configure the adapter in `PrismaService` / `database.prisma.adapter` instead of `PRISMA_ADAPTER`.
+
+### Option B — Prisma alongside JCC Eloquent
+
+Keep `DB_ORM=jcc` for Knex/JCC models and ensure `app/Config/database.ts` includes:
+
+```typescript
+import { PrismaService } from "@/Services/PrismaService";
+
+export const database = {
+  orm: config.get("DB_ORM", "jcc"),
+  prisma: {
+    service: PrismaService,
+  },
+  // ...
+};
+```
+
+`PrismaServiceProvider` registers the client whenever `database.prisma.service` is set.
+
+---
+
+## Required packages
+
+```bash
+npm install @prisma/client @prisma/adapter-mariadb
+npm install -D prisma
+```
+
+---
+
+## Initialize Prisma (new projects)
+
+After installing the packages, scaffold Prisma in your app **once** from the project root. Skip this step if `prisma/schema.prisma` already exists.
+
+```bash
+bun --bun x prisma init --datasource-provider mysql --output ./generated/prisma
+```
+
+Equivalent with `npx`:
+
+```bash
+npx prisma init --datasource-provider mysql --output ./generated/prisma
+```
+
+This creates:
+
+| File                   | Purpose                                      |
+| ---------------------- | -------------------------------------------- |
+| `prisma/schema.prisma` | Your Prisma schema                           |
+| `prisma.config.ts`     | CLI config (`DATABASE_URL`, migrations path) |
+
+Use `./generated/prisma` as the client output — **not** `../src/generated/prisma`. JCC Express MVC imports the client from `generated/prisma/client` (see `PrismaService` below).
+
+Set your database URL in `.env` before generating or migrating:
+
+```env
+DATABASE_URL="mysql://root:password@127.0.0.1:3306/your_database"
+```
+
+Then add `app/Services/PrismaService.ts` and wire `database.prisma.service` in `app/Config/database.ts` (see [App service class](#app-service-class)).
+
+---
+
+## Generate the client
+
+Generate the client after `prisma init` and whenever the schema changes:
+
+```bash
+bun artisanNode prisma:generate
+# or
+npm run prisma:generate
+```
+
+The generated client is written to `generated/prisma/` (gitignored — run `prisma:generate` after clone/CI install).
+
+Apply your first migration after generate:
+
+```bash
+bun artisanNode prisma:migrate init
+```
+
+---
+
+## App service class
+
+The framework only injects an adapter when you set `database.prisma.adapter` or `PRISMA_ADAPTER`. Otherwise `PrismaService` owns the adapter:
+
+```typescript
+import { PrismaClient } from "generated/prisma/client";
+import { createMariaDbAdapter } from "jcc-express-mvc/lib/Database/Drivers/Prisma/adapters/mariadb";
+import type { PrismaClientOptions } from "jcc-express-mvc/lib/Database/Drivers/Prisma/types";
+
+export class PrismaService extends PrismaClient {
+  constructor(options?: PrismaClientOptions) {
+    super({
+      adapter: options?.adapter ?? createMariaDbAdapter(), // your choice in the app
+    });
+  }
+}
+```
+
+When the framework **does** inject an adapter (`options.adapter`), it takes precedence over your fallback.
+
+---
+
+## Configuring an adapter
+
+Choose one approach:
+
+**1. In `PrismaService`** (app-owned — recommended when you want full control)
+
+**2. `PRISMA_ADAPTER` env** — uses a built-in factory:
+
+```env
+PRISMA_ADAPTER=postgres
+```
+
+**3. `database.prisma.adapter` in app config:**
+
+```typescript
+import { createPostgresAdapter } from "jcc-express-mvc/lib/Database/Drivers/Prisma/adapters/
+postgres";
+
+export const database = {
+  prisma: {
+    service: PrismaService,
+    adapter: () => createPostgresAdapter(),
+  },
+};
+```
+
+**Fully custom** — pass any Prisma 7 adapter instance or factory:
+
+```typescript
+import { PrismaPg } from "@prisma/adapter-pg";
+import { Pool } from "pg";
+
+prisma: {
+  service: PrismaService,
+  adapter: () => new PrismaPg(new Pool({ connectionString: process.env.DATABASE_URL })),
+},
+```
+
+`database.prisma.adapter` takes precedence over `PRISMA_ADAPTER`. If neither is set, the framework passes no adapter and `PrismaService` decides.
+
+---
+
+## Framework adapter helpers
+
+Built-in adapter factories:
+
+| Export                      | Use                                                 |
+| --------------------------- | --------------------------------------------------- |
+| `createPrismaAdapter(name)` | Build adapter for a named driver (`PRISMA_ADAPTER`) |
+| `createMariaDbAdapter()`    | MySQL / MariaDB                                     |
+| `createPostgresAdapter()`   | PostgreSQL                                          |
+| `createSqliteAdapter()`     | SQLite file                                         |
+| `createLibSqlAdapter()`     | LibSQL / Turso                                      |
+
+The framework registers `PrismaService` as a **singleton** and aliases `prisma` and `database.connection`.
+
+---
+
+## Using Prisma in controllers
+
+**Constructor injection** (recommended):
+
+```typescript
+import { Inject } from "jcc-express-mvc/Core/Dependency";
+import { PrismaService } from "@/Services/PrismaService";
+
+@Inject()
+export class UsersController {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async index() {
+    return await this.prisma.user.findMany();
+  }
+}
+```
+
+**Global helper**:
+
+```typescript
+const users = await prisma().user.findMany();
+```
+
+---
+
+## Schema and migrations
+
+Schema: `prisma/schema.prisma`  
+Migrations: `prisma/migrations/`  
+CLI config: `prisma.config.ts`
+
+```bash
+# Create & apply a migration (development)
+bun artisanNode prisma:migrate init
+
+# Apply pending migrations (production)
+bun artisanNode prisma:deploy
+
+# Push schema without migration files (prototyping)
+bun artisanNode prisma:push
+
+# Open Prisma Studio
+bun artisanNode prisma:studio
+```
+
+Equivalent npm scripts: `prisma:generate`, `prisma:migrate`, `prisma:studio`.
+
+---
+
+## Framework wiring
+
+| Piece                   | Location                                                     |
+| ----------------------- | ------------------------------------------------------------ |
+| `PrismaDriver`          | `jcc-express-mvc/lib/Database/Drivers/PrismaDriver.ts`       |
+| Driver adapters         | `jcc-express-mvc/lib/Database/Drivers/Prisma/adapters/`      |
+| `PrismaServiceProvider` | `jcc-express-mvc/lib/Database/PrismaServiceProvider.ts`      |
+| `Database` resolver     | `jcc-express-mvc/lib/Database/Database.ts` (`DB_ORM=prisma`) |
+
+When `DB_ORM=prisma` (or when `database.prisma.service` is set in `app/Config/database.ts`):
+
+- Your `PrismaService` class is registered as a **singleton**.
+- The client is available via constructor injection, `app.resolve("prisma")`, or the global `prisma()` helper.
+- Knex / Sequelize / Mongoose setup is skipped so Prisma owns the database connection.
+- The client disconnects gracefully on shutdown.
+
+---
+
+## Related
+
+- [Database Introduction](./Database-Introduction.md)
+- [ArtisanNode](../The%20Basics/Artisan-Node.md)
+- [Service Provider](../Architecture%20Concept/Service-Provider.md)

package/final-documentation/Database/Query-Builder.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-JCC Express MVC provides a fluent query builder through `DB.table(...)` and `DB.query()` (`jcc-express-mvc/lib/Jcc-eloquent/lib/Builder.ts`).
+JCC Express MVC provides a fluent query builder through `DB.table(...)` and `DB.query()`.
 
 Use it for composable SQL queries without writing full raw SQL for every operation.
 

package/final-documentation/Database/Seeding.md

@@ -23,7 +23,7 @@ This creates a new seeder class in `database/seeders`.
 Typical seeder pattern:
 
 ```typescript
-import { DB } from "jcc-express-mvc/lib/Jcc-eloquent";
+import { DB } from "jcc-express-mvc/Eloquent";
 
 export class UserSeeder {
   async run() {