jcc-express-mvc 1.9.2 → 1.9.4

package/final-documentation/Database/Migrations.md

@@ -0,0 +1,319 @@
+# Migrations
+
+## Introduction
+
+Migrations are version-controlled schema changes for your database. In JCC Express MVC, migrations are generated and executed through `artisanNode`.
+
+Migration files live in `database/migrations`.
+
+---
+
+## Generate a migration
+
+```bash
+bun artisanNode make:migration create_users_table
+```
+
+This creates a timestamped migration file in `database/migrations`.
+
+You can also generate queue-related tables:
+
+```bash
+bun artisanNode make:queue-table
+```
+
+---
+
+## Typical migration structure
+
+A migration defines schema changes in `up`/`down` style methods (depending on your migration template in this project).
+
+Common operations include:
+
+- creating tables
+- adding/removing columns
+- indexes/constraints
+- dropping tables
+
+Keep each migration focused on one schema change.
+
+---
+
+## Migration schema examples
+
+### Create table schema
+
+```typescript
+import { Schema } from "jcc-express-mvc/Eloquent";
+
+export class Migration {
+  up() {
+    return Schema.create("posts", (table) => {
+      table.id();
+      table.string("title");
+      table.string("slug").unique();
+      table.text("excerpt").nullable();
+      table.longText("content");
+      table.boolean("is_published", false);
+      table.integer("sort_order").unsigned().default(0);
+      table.json("meta").nullable();
+      table.date("published_at").nullable();
+      table.timestamps();
+      table.softDeletes();
+    });
+  }
+
+  down() {
+    return Schema.dropTable("posts");
+  }
+}
+```
+
+### Foreign keys and composite unique
+
+```typescript
+import { Schema } from "jcc-express-mvc/Eloquent";
+
+export class Migration {
+  up() {
+    return Schema.create("post_comments", (table) => {
+      table.id();
+      table.foreignId("post_id").references("id").on("posts");
+      table.foreignId("user_id").references("id").on("users");
+      table.text("body");
+      table.timestamps();
+
+      table.compositeUnique(
+        ["post_id", "user_id", "created_at"],
+        "uk_post_comments_post_user_created"
+      );
+    });
+  }
+
+  down() {
+    return Schema.dropTable("post_comments");
+  }
+}
+```
+
+### Alter existing table
+
+```typescript
+import { Schema } from "jcc-express-mvc/Eloquent";
+
+export class Migration {
+  up() {
+    return Schema.table("users", (table) => {
+      table.string("phone").nullable();
+      table.boolean("is_verified", false);
+    });
+  }
+
+  down() {
+    return Schema.table("users", (table) => {
+      table.dropColumns("phone", "is_verified");
+    });
+  }
+}
+```
+
+Common schema helpers seen in the current codebase:
+
+- `id()`
+- `string()`
+- `text()`
+- `longText()`
+- `integer()`, `smallInteger()`, `unsignedBigInteger()`
+- `boolean()`
+- `json()`
+- `date()`
+- `timestamps()`
+- `softDeletes()`
+- `foreignId(...).references(...).on(...)`
+- `foreign(...).references(...).on(...)`
+- `compositeUnique(columns, indexName)`
+
+---
+
+## 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`
+
+### `Schema` methods
+
+- `create(tableName, callback)`
+- `table(tableName, callback)`
+- `dropTable(tableName)`
+- `dropIfExists(tableName)`
+- `truncate(tableName)`
+- `drop(tableName)`
+- `rename(from, to)`
+- `hasTable(tableName)`
+- `hasColumn(tableName, columnName)`
+
+### `Blueprint` column types
+
+- `id()`
+- `unsignedBigInteger(column)`
+- `string(column, length?)`
+- `integer(column)`
+- `bigInteger(column)`
+- `tinyInteger(column, size?)`
+- `smallInteger(column)`
+- `mediumInteger(column)`
+- `unsignedSmallInteger(column)`
+- `unsignedMediumInteger(column)`
+- `unsignedInteger(column)`
+- `unsignedTinyInteger(column)`
+- `char(column, length?)`
+- `text(column)`
+- `mediumText(column)`
+- `longText(column)`
+- `tinyText(column)`
+- `binary(column, size?)`
+- `blob(column)`
+- `tinyBlob(column)`
+- `mediumBlob(column)`
+- `longBlob(column)`
+- `dateTime(column)`
+- `date(column)`
+- `timestamp(column)`
+- `time(column)`
+- `year(column)`
+- `enum(column, values?)`
+- `boolean(column, defaultValue?)`
+- `float(column, total?, places?)`
+- `double(column, total?, places?)`
+- `decimal(column, total?, places?)`
+- `json(column)`
+- `jsonb(column)`
+- `uuid(column)`
+- `set(column, values?)`
+- `foreignId(column)`
+- `uuidPrimaryKey(column?)`
+- `ulid(column)`
+- `ulidPrimaryKey(column?)`
+- `ipAddress(column)`
+- `macAddress(column)`
+- `geometry(column)`
+- `point(column)`
+- `polygon(column)`
+- `lineString(column)`
+
+### `Blueprint` relationships and morphs
+
+- `foreign(column)`
+- `references(column)`
+- `on(table)`
+- `foreignIdFor(model, column?, table?)`
+- `constrained(table, column?)`
+- `morphs(column)`
+- `nullableMorphs(column)`
+- `uuidMorphs(column)`
+- `nullableUuidMorphs(column)`
+- `dropMorphs(column)`
+
+### `Blueprint` modifiers and column controls
+
+- `default(value)`
+- `nullable()`
+- `unique()`
+- `change()`
+- `after(column)`
+- `first()`
+- `autoIncrement()`
+- `unsigned()`
+- `useCurrent()`
+- `useCurrentOnUpdate()`
+- `storedAs(expression)`
+- `virtualAs(expression)`
+- `charset(charset)`
+- `collation(collation)`
+- `check(expression)`
+- `renameColumn(from, to)`
+- `dropColumns(...columns)`
+
+### `Blueprint` indexes and constraints
+
+- `index(indexNameOrColumns?)`
+- `dropIndex(indexName)`
+- `dropUnique(indexName)`
+- `dropForeign(indexName)`
+- `dropPrimary()`
+- `fulltext(columns)`
+- `spatialIndex(columns)`
+- `compositeIndex(columns, indexName?)`
+- `compositeUnique(columns, indexName?)`
+
+### `Blueprint` timestamps, soft deletes, and token helpers
+
+- `timestamps(createdAt?, updatedAt?)`
+- `nullableTimestamps()`
+- `softDeletes(column?)`
+- `dropTimestamps()`
+- `dropSoftDeletes(column?)`
+- `rememberToken()`
+- `dropRememberToken()`
+
+### `Blueprint` table-level options
+
+- `engine(engine)`
+- `tableCharset(charset)`
+- `tableCollation(collation)`
+- `comment(comment)`
+- `temporary()`
+- `toSQL(actionType?, tableName)`
+
+### Foreign key action helpers
+
+- `cascade()`
+- `onDelete(action?)`
+- `onUpdate(action?)`
+- `cascadeOnDelete()`
+- `cascadeOnUpdate()`
+
+---
+
+## Run migrations
+
+```bash
+bun artisanNode migrate
+```
+
+Runs all pending migrations.
+
+---
+
+## Rollback and reset
+
+```bash
+bun artisanNode migrate:rollback
+bun artisanNode migrate:rollback step=2
+bun artisanNode migrate:reset
+bun artisanNode migrate:fresh
+```
+
+- `migrate:rollback` -> rolls back the last batch (or given steps)
+- `migrate:reset` -> rolls back all migrations
+- `migrate:fresh` -> drops all tables, then reruns migrations
+
+---
+
+## Best practices
+
+- Keep migrations small and reviewable.
+- Never edit old migrations that already ran in shared environments; add a new migration instead.
+- Test rollback paths for critical schema changes.
+- Run migrations in CI/CD before app starts serving traffic.
+
+---
+
+## Summary
+
+- Generate with `make:migration`.
+- Apply with `migrate`.
+- Revert with rollback/reset/fresh commands.
+- Keep migration history append-only and environment-safe.

package/final-documentation/Database/Mongoose.md

@@ -0,0 +1,125 @@
+# Mongoose
+
+## Introduction
+
+JCC Express MVC supports MongoDB through a Mongoose driver (`MongooseDriver`) selected by database config/env.
+
+When enabled, the framework resolves and registers the Mongoose connection as:
+
+- `database.connection`
+- `mongoose`
+
+---
+
+## Enable Mongoose
+
+Set env values for mongo mode:
+
+```env
+DB_ORM=mongoose
+DB_CONNECTION=mongodb
+DB_HOST=127.0.0.1
+DB_PORT=27017
+DB_DATABASE=your_db
+DB_USERNAME=
+DB_PASSWORD=
+```
+
+`app/Config/database.ts` includes the expected `mongoose` block:
+
+```typescript
+mongoose: {
+  host,
+  port,
+  database,
+  username,
+  password,
+  options: {},
+}
+```
+
+---
+
+## Required packages
+
+Install Mongoose:
+
+```bash
+npm install mongoose
+```
+
+---
+
+## Generate models (recommended)
+
+Do not manually write model files. Use ArtisanNode:
+
+```bash
+bun artisanNode make:model User
+```
+
+Keep your Mongo-oriented model definitions in `app/Models` so the project structure stays consistent.
+
+---
+
+## Mongoose model example
+
+In Mongoose mode, a model file can follow this shape:
+
+```typescript
+import mongoose, { HydratedDocument, InferSchemaType, Schema } from "mongoose";
+
+const UserSchema = new Schema(
+  {
+    name: { type: String, required: true },
+    email: { type: String, unique: true, required: true },
+    password: { type: String, required: true },
+  },
+  { timestamps: true },
+);
+
+export const User = mongoose.model("User", UserSchema);
+export type User = HydratedDocument<InferSchemaType<typeof UserSchema>>;
+```
+
+The exported model name `User` is important in this project for route model binding conventions.
+
+---
+
+## Connection behavior
+
+From `MongooseDriver`:
+
+- builds URI as `mongodb://[username:password@]host:port/database`
+- runs `mongoose.connect(uri, options)`
+- keeps a shared connection reference for the app lifecycle
+
+Disconnect path uses `mongoose.disconnect()`.
+
+---
+
+## Access the Mongoose connection
+
+```typescript
+const mongooseConn = app.resolve("mongoose");
+```
+
+The instance is registered by `DatabaseServiceProvider`.
+
+---
+
+## Notes
+
+- Driver selection is triggered by `DB_ORM=mongoose` or `DB_CONNECTION=mongodb`.
+- If host/database are missing, URI construction fails and connect throws.
+- Keep Mongo-specific schema/model logic separate from SQL/JCC query-builder code paths.
+
+---
+
+## Summary
+
+- Set `DB_ORM=mongoose`.
+- Configure the `mongoose` section in `app/Config/database.ts`.
+- Install `mongoose`.
+- Generate models with `bun artisanNode make:model User`.
+- Resolve connection via `app.resolve("mongoose")`.

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

@@ -0,0 +1,181 @@
+# Query Builder
+
+## Introduction
+
+JCC Express MVC provides a fluent query builder through `DB.table(...)` and `DB.query()` (`jcc-express-mvc/lib/Jcc-eloquent/lib/Builder.ts`).
+
+Use it for composable SQL queries without writing full raw SQL for every operation.
+
+---
+
+## Starting queries
+
+```typescript
+const q1 = DB.table("users");
+const q2 = DB.query().from("users");
+```
+
+Select columns:
+
+```typescript
+const rows = await DB.table("users").select("id", "name", "email").get();
+```
+
+---
+
+## Read methods
+
+```typescript
+const all = await DB.table("users").get();
+const first = await DB.table("users").where("id", 1).first();
+const found = await DB.table("users").find(1);
+
+const exists = await DB.table("users").where("email", email).exists();
+const notExists = await DB.table("users").where("email", email).doesntExist();
+const oneValue = await DB.table("users").where("id", 1).value("email");
+```
+
+---
+
+## Where clauses
+
+```typescript
+const rows = await DB.table("users")
+  .where("active", true)
+  .where("age", ">", 18)
+  .orWhere("role", "admin")
+  .whereNull("deleted_at")
+  .get();
+```
+
+Other common filters:
+
+- `whereNot(...)`, `orWhereNot(...)`
+- `whereNotNull(...)`
+- `whereIn(...)`
+- `whereBetween(...)`, `whereNotBetween(...)`
+- `whereDate(...)`, `whereMonth(...)`, `whereDay(...)`, `whereYear(...)`, `whereTime(...)`
+- `whereLike(...)`, `orWhereLike(...)`
+- `whereRaw(...)`, `orWhereRaw(...)`
+- `whereColumn(...)`, `orWhereColumn(...)`, `whereNotColumn(...)`
+- `whereJson(...)`, `orWhereJson(...)`
+- `whereExists(...)`, `orWhereExists(...)`
+
+---
+
+## Ordering, grouping, and having
+
+```typescript
+const report = await DB.table("orders")
+  .select("status")
+  .select(DB.raw("count(*) as total"))
+  .groupBy("status")
+  .having("status", "!=", "cancelled")
+  .orderBy("total", "desc")
+  .get();
+```
+
+Also available:
+
+- `latest(column?)`, `older(column?)`
+- `orderByRaw(...)`
+- `groupByRaw(...)`
+- `havingIn(...)`, `havingNotIn(...)`
+- `havingNull(...)`, `havingNotNull(...)`
+- `havingBetween(...)`, `havingNotBetween(...)`
+- `havingRaw(...)`
+
+---
+
+## Joins
+
+```typescript
+const rows = await DB.table("posts")
+  .join("users", "posts.user_id", "=", "users.id")
+  .leftJoin("comments", "comments.post_id", "=", "posts.id")
+  .select("posts.*", "users.name as author")
+  .get();
+```
+
+Join variants:
+
+- `innerJoin(...)`
+- `leftJoin(...)`
+- `rightJoin(...)`
+- `leftOuterJoin(...)`
+- `rightOuterJoin(...)`
+- `fullOuterJoin(...)`
+- `joinRaw(...)`
+- subquery joins: `joinSub(...)`, `leftJoinSub(...)`, `rightJoinSub(...)`, `crossJoinSub(...)`
+
+---
+
+## Write methods
+
+```typescript
+await DB.table("users").insert({ name: "Abdou", email: "abdou@example.com" });
+
+await DB.table("users").where("id", 1).update({ name: "Abdou J" });
+await DB.table("users").where("id", 1).updateQuietly({ name: "No Events" });
+
+await DB.table("users").where("id", 1).delete();
+await DB.table("users").where("id", 1).deleteQuietly();
+```
+
+Counters and JSON updates:
+
+```typescript
+await DB.table("users").where("id", 1).increment("login_count", 1);
+await DB.table("users").where("id", 1).decrement("credits", 2);
+await DB.table("users").where("id", 1).updateJson("profile->theme", "dark");
+```
+
+---
+
+## Aggregates and pagination
+
+```typescript
+const total = await DB.table("users").count("id");
+const maxScore = await DB.table("users").max("score");
+const minScore = await DB.table("users").min("score");
+const sumScore = await DB.table("users").sum("score");
+const avgScore = await DB.table("users").avg("score");
+
+const page = await DB.table("users").orderBy("id", "desc").paginate(1, 15);
+```
+
+Pagination returns a page payload (data + metadata) from builder internals.
+
+---
+
+## Raw SQL and transactions
+
+```typescript
+const rows = await DB.runQuery("select * from users where active = ?", [1]);
+const rawExpr = DB.raw("count(*) as total");
+
+await DB.transaction(async () => {
+  await DB.table("wallets").where("id", 1).decrement("balance", 100);
+  await DB.table("wallets").where("id", 2).increment("balance", 100);
+});
+```
+
+---
+
+## Utility methods
+
+- `clone()` -> duplicate a query
+- `toSQL()` / `toSqlCode()` -> inspect generated SQL
+- `offset(...)`, `limit(...)`
+- `distinct(...)`
+- `pluck(...)`
+- `union(...)`, `unionAll(...)`
+- `truncate()`
+
+---
+
+## Summary
+
+- Use `DB.table(...)` for most query-builder workflows.
+- Chain filters/joins/groups, then finalize with `get`, `first`, `insert`, `update`, `delete`, etc.
+- Use `runQuery` / `raw` for advanced SQL and `DB.transaction(...)` for atomic operations.

package/final-documentation/Database/Seeding.md

@@ -0,0 +1,93 @@
+# Seeding
+
+## Introduction
+
+Seeders populate your database with initial or test data (roles, admin users, fixtures, demo content).
+
+Seeders live in `database/seeders` and are executed through `artisanNode`.
+
+---
+
+## Generate a seeder
+
+```bash
+bun artisanNode make:seeder UserSeeder
+```
+
+This creates a new seeder class in `database/seeders`.
+
+---
+
+## Write seeder data
+
+Typical seeder pattern:
+
+```typescript
+import { DB } from "jcc-express-mvc/lib/Jcc-eloquent";
+
+export class UserSeeder {
+  async run() {
+    await DB.table("users").insert([
+      { name: "Admin", email: "admin@example.com" },
+      { name: "Editor", email: "editor@example.com" },
+    ]);
+  }
+}
+```
+
+Use framework helpers for sensitive values when needed:
+
+```typescript
+const password = await bcrypt("secret");
+```
+
+---
+
+## Run seeders
+
+Run default seeding flow (this executes `DatabaseSeeder` in `database/seeders`):
+
+```bash
+bun artisanNode db:seed
+```
+
+Run a specific seeder class:
+
+```bash
+bun artisanNode db:seed class=UserSeeder
+```
+
+---
+
+## Common workflows
+
+### Fresh database + seed
+
+```bash
+bun artisanNode migrate:fresh
+bun artisanNode db:seed
+```
+
+### Queue table + seed app data
+
+```bash
+bun artisanNode make:-table
+bun artisanNode migrate
+bun artisanNode db:seed
+```
+
+---
+
+## Best practices
+
+- Make seeders idempotent where possible (safe to rerun).
+- Keep production seeders minimal (required baseline data only).
+- Separate large demo/test fixtures from critical app bootstrap data.
+
+---
+
+## Summary
+
+- Create seeders with `make:seeder`.
+- Execute with `db:seed`.
+- Combine with migrations for repeatable environment setup.