jcc-express-mvc 1.9.6 → 1.9.7

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

@@ -32,7 +32,8 @@ The abstract base class lives in `jcc-express-mvc` (`ServiceProvider`). Extend i
 
 In `withProviders()`, the builder does not use your array alone. It builds this chain:
 
-1. `DatabaseServiceProvider` — Always first (database-related setup).
+1. `DatabaseServiceProvider` — Knex / Sequelize / Mongoose setup (skipped when `DB_ORM=prisma`).
+2. `PrismaServiceProvider` — Prisma client singleton and graceful `$disconnect`.
 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.
 
@@ -98,6 +99,7 @@ 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.
 - `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,7 @@ 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
 
 In practice, most projects start with the default JCC stack, then switch ORM mode only when needed.
 
@@ -23,6 +24,8 @@ 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).
+
 ---
 
 ## Configuration
@@ -38,11 +41,14 @@ Minimal shape from `app/Config/database.ts`:
 ```typescript
 export const database = {
   orm: config.get("DB_ORM", "jcc"),
+  prisma: { service: PrismaService },
   sequelize: { /* ... */ },
   mongoose: { /* ... */ },
 };
 ```
 
+See [Prisma](./Prisma.md) for the full Prisma setup.
+
 ---
 
 ## SQLite configuration

package/final-documentation/Database/Prisma.md

@@ -0,0 +1,275 @@
+# 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 "@framework/lib/Database/Drivers/Prisma/adapters/mariadb";
+import type { PrismaClientOptions } from "@framework/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
+
+| Export                      | Use                                                 |
+| --------------------------- | --------------------------------------------------- |
+| `resolvePrismaAdapter(app)` | Used by `PrismaServiceProvider`                     |
+| `createPrismaAdapter(name)` | Build adapter for a named driver (`PRISMA_ADAPTER`) |
+| `createMariaDbAdapter()`    | MySQL / MariaDB                                     |
+| `createPostgresAdapter()`   | PostgreSQL                                          |
+| `createSqliteAdapter()`     | SQLite file                                         |
+| `createLibSqlAdapter()`     | LibSQL / Turso                                      |
+
+Import from `jcc-express-mvc/lib/Database` or `jcc-express-mvc/lib/Database/Drivers/Prisma/connection`.
+
+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`) |
+
+`PrismaDriver` implements the same `DatabaseDriver` interface as `KnexDriver`, `SequelizeDriver`, and `MongooseDriver` (`connect`, `getConnection`, `disconnect`). Adapter selection lives under `Drivers/Prisma/`.
+
+When `DB_ORM=prisma`, `DatabaseServiceProvider` skips Knex/Sequelize/Mongoose setup so only Prisma owns the connection.
+
+---
+
+## Related
+
+- [Database Introduction](./Database-Introduction.md)
+- [ArtisanNode](../The%20Basics/Artisan-Node.md)
+- [Service Provider](../Architecture%20Concept/Service-Provider.md)

package/final-documentation/Database/TypeORM.md

@@ -0,0 +1,240 @@
+# TypeORM
+
+## Introduction
+
+JCC Express MVC supports [TypeORM](https://typeorm.io/) as an ORM option via `DB_ORM=typeorm`. TypeORM uses decorator-based **entities** in `app/Entities/` — separate from JCC Eloquent models in `app/Model/` and Sequelize/Mongoose files in `app/Models/`.
+
+You can also use TypeORM **alongside** JCC Eloquent by keeping `DB_ORM=jcc` and configuring `database.typeorm.dataSource` in `app/Config/database.ts` (the framework still registers a singleton `DataSource`).
+
+---
+
+## Enable TypeORM
+
+### Option A — TypeORM as primary ORM
+
+```env
+DB_ORM=typeorm
+DB_CONNECTION=mysql2
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=your_database
+DB_USERNAME=root
+DB_PASSWORD=password
+
+# Development only — use migrations in production
+TYPEORM_SYNCHRONIZE=false
+TYPEORM_LOGGING=false
+```
+
+`DB_CONNECTION` is mapped to a TypeORM driver:
+
+| `DB_CONNECTION`                | TypeORM type     |
+| ------------------------------ | ---------------- |
+| `mysql2`, `mysql`, `mariadb`   | `mysql`          |
+| `postgres`, `postgresql`, `pg` | `postgres`       |
+| `sqlite`, `better-sqlite3`     | `better-sqlite3` |
+
+### Option B — TypeORM alongside JCC Eloquent
+
+Keep `DB_ORM=jcc` for Knex/JCC models and ensure `app/Config/database.ts` includes:
+
+```typescript
+import { TypeORMDataSource } from "@/Services/TypeORMDataSource";
+
+export const database = {
+  orm: config.get("DB_ORM", "jcc"),
+  typeorm: {
+    dataSource: TypeORMDataSource,
+    autoloadEntities: true,
+    synchronize: false,
+    logging: false,
+  },
+  // ...
+};
+```
+
+`TypeORMServiceProvider` registers the client whenever `database.typeorm.dataSource` is set.
+
+---
+
+## Required packages
+
+```bash
+npm install typeorm
+```
+
+Install the driver for your database (already common in JCC apps):
+
+```bash
+npm install mysql2    # MySQL / MariaDB
+npm install pg        # PostgreSQL
+npm install better-sqlite3   # SQLite
+```
+
+---
+
+## App DataSource class
+
+`app/Services/TypeORMDataSource.ts` extends TypeORM `DataSource` and reads connection settings from `DB_*` env vars:
+
+```typescript
+import { DataSource } from "typeorm";
+import { typeORMOptionsFromEnv } from "jcc-express-mvc/lib/Database/Drivers/TypeORM/connection";
+import type { TypeORMDataSourceOptions } from "jcc-express-mvc/lib/Database/Drivers/TypeORM/types";
+
+export class TypeORMDataSource extends DataSource {
+  constructor(options?: TypeORMDataSourceOptions) {
+    super(typeORMOptionsFromEnv(options));
+  }
+}
+```
+
+Wire it in `app/Config/database.ts`:
+
+```typescript
+typeorm: {
+  dataSource: TypeORMDataSource,
+  autoloadEntities: true,
+  synchronize: config.get("TYPEORM_SYNCHRONIZE", "false") === "true",
+  logging: config.get("TYPEORM_LOGGING", "false") === "true",
+},
+```
+
+When the driver connects, it scans `app/Entities/` for `.ts`/`.js` files and registers exported entity classes (unless `autoloadEntities: false` or you pass `entities` explicitly).
+
+---
+
+## Define entities
+
+Place entities in `app/Entities/`:
+
+```typescript
+import { Entity, PrimaryGeneratedColumn, Column, OneToMany } from "typeorm";
+import { Post } from "./Post";
+
+@Entity({ name: "users" })
+export class User {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ unique: true })
+  email!: string;
+
+  @Column({ nullable: true })
+  name?: string;
+
+  @Column({ select: false })
+  password!: string;
+
+  @OneToMany(() => Post, (post) => post.author)
+  posts!: Post[];
+}
+```
+
+Generate a new entity with ArtisanNode:
+
+```bash
+bun artisanNode make:model Product
+```
+
+When `DB_ORM=typeorm`, `make:model` scaffolds into `app/Entities/` with TypeORM decorators.
+
+---
+
+## Using TypeORM in controllers
+
+**Constructor injection** (recommended):
+
+```typescript
+import { Inject } from "jcc-express-mvc/Core/Dependency";
+import { TypeORMDataSource } from "@/Services/TypeORMDataSource";
+import { User } from "@/Entities/User";
+
+@Inject()
+export class UsersController {
+  constructor(private readonly db: TypeORMDataSource) {}
+
+  async index() {
+    return this.db.getRepository(User).find();
+  }
+
+  async show(id: number) {
+    return this.db.getRepository(User).findOne({
+      where: { id },
+      relations: { posts: true },
+    });
+  }
+}
+```
+
+**Global helper**:
+
+```typescript
+import { User } from "@/Entities/User";
+
+const users = await typeorm().getRepository(User).find();
+```
+
+---
+
+## Auth and route model binding
+
+When `DB_ORM=typeorm`, framework helpers resolve users and route-bound models via TypeORM repositories:
+
+- `findUserById`, `findUserForAuth`
+- `resolveModelBinding`
+- `AuthMiddleware` API auth lookup
+
+`getModel("User")` loads from `app/Entities/User` instead of `app/Models/`.
+
+---
+
+## Migrations (TypeORM CLI)
+
+Use the TypeORM CLI directly for migrations (not yet wrapped in ArtisanNode):
+
+```bash
+# Generate a migration from entity changes
+npx typeorm migration:generate -d app/Services/TypeORMDataSource.ts migrations/Init
+
+# Run migrations
+npx typeorm migration:run -d app/Services/TypeORMDataSource.ts
+```
+
+For local prototyping only, `TYPEORM_SYNCHRONIZE=true` auto-syncs schema from entities. **Do not use synchronize in production.**
+
+---
+
+## Framework wiring
+
+| Piece                    | Location                                                      |
+| ------------------------ | ------------------------------------------------------------- |
+| `TypeORMDriver`          | `jcc-express-mvc/lib/Database/Drivers/TypeORMDriver.ts`       |
+| `TypeORMServiceProvider` | `jcc-express-mvc/lib/Database/TypeORMServiceProvider.ts`      |
+| Connection helpers       | `jcc-express-mvc/lib/Database/Drivers/TypeORM/connection.ts`  |
+| `Database` resolver      | `jcc-express-mvc/lib/Database/Database.ts` (`DB_ORM=typeorm`) |
+
+`TypeORMDriver` implements the same `DatabaseDriver` interface as other drivers (`connect`, `getConnection`, `disconnect`).
+
+When `DB_ORM=typeorm`, `DatabaseServiceProvider` skips Knex/Sequelize/Mongoose setup so only TypeORM owns the connection. Prisma and TypeORM do not register together when one is the primary `DB_ORM`.
+
+The database **monitor** query collector is Knex-only; it is skipped automatically when `DB_ORM` is not `jcc`.
+
+---
+
+## Demo routes
+
+This repo includes `TestTypeORMController` with routes under `/api/typeorm` when TypeORM is configured:
+
+- `GET /api/typeorm` — list users with posts
+- `POST /api/typeorm` — create sample user and post
+- `GET /api/typeorm/:id` — show one user
+
+---
+
+## Related
+
+- [Database Introduction](./Database-Introduction.md)
+- [Configuration](../Getting-Started/Configuration.md)
+- [Helpers](../Digging%20Deeper/Helpers.md)
+- [Service Provider](../Architecture%20Concept/Service-Provider.md)

package/final-documentation/Digging Deeper/Helpers.md

@@ -41,6 +41,12 @@ These depend on per-request container bindings, so they are request-lifecycle he
 - `can(user, ability, model?, ...args)`
 - `authorize(user, ability, ...args)`
 
+---
+
+## Database helpers
+
+- `prisma()` -> registered Prisma client singleton (when `database.prisma.service` is configured or `DB_ORM=prisma`)
+
 Also available:
 
 - `bcrypt(value)`

package/final-documentation/Getting-Started/Configuration.md

@@ -33,7 +33,7 @@ Use a full URL for `APP_URL` in production (for example `https://example.com`).
 
 ### Database and ORM
 
-- `DB_ORM` — `jcc` (Knex / JCC Eloquent), `sequelize`, or `mongoose`.
+- `DB_ORM` — `jcc` (Knex / JCC Eloquent), `sequelize`, `mongoose`, or `prisma`.
 - `DB_CONNECTION` — Driver for Knex (for example `mysql2`, `postgres`, `sqlite`, `better-sqlite3`).
 - `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` — Connection details.
 

package/final-documentation/Getting-Started/Directory-structure.md

@@ -35,7 +35,7 @@ Other roots you may see in a mature repo include `design/` (schemas, design note
 ## `app/` — application code
 
 - `Config/` — Typed config modules merged in `app/Config/index.ts` (see [Configuration.md](./Configuration.md)).
-- `Http/` — `kernel.ts`, `Controllers/`, `ApiControllers/`, `Middlewares/`, `Requests/`.
+- `Http/` — `kernel.ts`, `Controllers/`, `ApiControllers/`, `Middlewares/`, `Requests/`, `Resources/`.
 - `Models/` — Eloquent (or other ORM) models.
 - `Providers/` — Service providers (`AppServiceProvider`, queues, sockets, etc.).
 - `Console/Command/` — Custom `artisanNode` commands.

package/final-documentation/Security/Authentication.md

@@ -107,7 +107,7 @@ For stateless API clients, use `auth().apiAttempt()` to validate credentials and
 
 ```typescript
 Route.post("/api/login", async () => {
-  const result = await auth().apiAttempt({ field: "email", table: "User" });
+  const result = await auth().apiAttempt({ field: "email", model: "User" });
 
   if (!result.success) {
     return response().status(401).json({ message: result.message });
@@ -129,7 +129,7 @@ Route.middleware(["apiAuth"]).get("/api/me", async (req) => {
 | Field | Default | Description |
 |---|---|---|
 | `field` | `"email"` | Request input key to match (`email`, `phone`, `username`, etc.) |
-| `table` | `"User"` | Model name resolved via `getModel()` |
+| `model` | `"User"` | Model name resolved via `getModel()` |
 
 The request body must include the credential field and `password`. On success, returns `{ success: true, token, user, message }`. On failure, returns `{ success: false, token: null, user: null, message: "Invalid credentials" }`.