jcc-express-starter

A Laravel-inspired MVC framework for Express.js

Warning

Note: This package is not recommended for use in production environments. It's intended for learning purposes only. Use in production at your own risk.

jcc-express-mvc Framework Documentation

Table of Contents

• Introduction
• Core Features
• Installation
• Quick Start Guide
• ArtisanNode CLI
• Project Structure
• Routing
• Controllers
• Middelwares
• ORM (jcc-eloquent)
• Validation
• Form Requests
• Service Container & Dependency Injection
• Frontend
  • jsBlade Templating
  • Inertia.js Integration
• Service Providers
  • Route Service Provider
  • Custom Providers
• Helpers -String utility
• TinkerNode

jcc-express-starter

Introduction

jcc-express-mvc is a lightweight Node.js package that simplifies the development of Express.js applications using a structure inspired by Laravel's file organization. It encourages the use of the Model-View-Controller (MVC) architectural pattern, providing a clean and organized approach to building and scaling your Express.js projects.

Core Features

• Express.js Framework (jcc-express-starter)

  • Sets up an Express.js web application with MVC architecture
  • Opinionated project structure for organized code
  • Built-in validation methods
  • Two routes file for easy route management
  • Comes with jsBlade similar to Laravel blade for view rendering, but you can use any templating engine of choice
  • Includes configuration with MySQL
  • Includes configuration with dotenv

• ORM (jcc-eloquent)

  • Query Builder with methods for complex SQL operations
  • Model system with fillable, guarded, and casts properties
  • Relationships, including polymorphic relations (morphMany)
  • Event hooks (e.g., creating, booted) for action triggers
  • Schema Builder for migrations, inspired by Laravel's schema API

Installation

Prerequisites

• Node.js and npm installed
• ts-node globally installed

Make sure you have Node.js and npm (Node Package Manager) installed and install ts-node globally on your machine. To create a new Express.js project using jcc-express-starter, simply run the following command in your terminal:

1npx jcc-express-starter my-express-app

Quick Start Guide

This will create a new directory named my-express-app and set up the Express.js application inside it.

1. Navigate to the newly created directory:

1cd my-express-app

2. Configure Environment

Edit the .env file to configure your database and other environment-specific settings. Example .env:

1APP_SESSION_SECTRET=app-session-1203-4-556-22
2PORT=5500
3
4DB_CONNECTION=mysql
5DB_HOST=127.0.0.1
6DB_PORT=3306
7DB_DATABASE=my_database
8DB_USERNAME=root
9DB_PASSWORD=password

3. Start the application:

1# start vite
2npm run watch
3# start development server
4npm run dev
5

ArtisanNode CLI

Generate Controllers, Models, Migrations, and Seeders:

1ts-node artisanNode make:controller UsersController # Controller
2ts-node artisanNode make:model User # Model
3ts-node artisanNode make:request UserRequest # Request
4ts-node artisanNode make:model User -mcr  # Model, Controller, Migration
5ts-node artisanNode make:model User -mcsr # Model, Controller, Migration, Seeder

Run Database Migrations:

1ts-node artisanNode migrate
2ts-node artisanNode migrate:rollback            # Undo the last migration
3ts-node artisanNode migrate:rollback --steps=3  # Undo multiple migrations
4ts-node artisanNode migrate:fresh               # Reset migrations and re-run
5ts-node artisanNode migrate:reset               # Reset migrations
6ts-node artisanNode db:seed                     # Run seeders
7ts-node artisanNode db:seed --class=UserSeeder  # Check for UserSeeder in the seeders and run the seeder

Project Structure

1project-root/
2|--app
3| |--Config/
4| | | --app.ts
5| | |--egine.ts
6| |--Http
7| | |--Controllers/
8| | | |--UsersController.ts
9| | |--Middlewares/
10| | |--Request/
11| | |  |--UserRequest.ts
12| | |--kernel.ts
13| |--Models/
14| | |--User.ts
15| |--Providers
16| | |--AppServiceProvider.ts
17| | |--RouteServiceProvider.ts
18|--bootstrap
19| |-app.ts
20|--database
21| |--migrations
22| | |--create_users_table.ts
23| |--seeders
24| | |--UserSeeder.ts
25|--public/
26| |--css/
27| | |--app.css
28| |--js/
29| | |--app.js
30|--resources/
31| |--views/
32| | |--partials/
33| | | |--header.blade.html
34| | |--layout/layout.blade.html
35| | |--index.blade.html
36| |--css/
37| | |--app.css
38| |--js/
39| | |--app.js
40|--routes/
41| |--web.ts
42| |--api.ts

• app/Config/: Configuration files for the application
• app/Http/Controllers/: Controllers handling the application logic
• app/Models/: Models for database interactions
• app/Providers: Service providers for the application
• public/: Static assets like CSS and JavaScript files
• routes/: Two routes file (web.js | api.js) where routes are registered
• resources/views/: jsBlade templates for rendering views
• server.ts: Main application file
• app/Htpp/kernel.ts: Global middlewares

Routing

Basic routing is meant to route your request to an appropriate controller. The routes of the application can be defined in route/web.js or route/api.js file. Here is the general route syntax for each of the possible request. You can define the URLs of your application with the help of routes. These routes can contain variable data, connect to controllers or can be wrapped into middlewares.

1import { Route } from "jcc-express-mvc/Route";
2import { auth } from "jcc-express-mvc";
3import { UsersController } from "@Controllers/UsersController";
4
5Route.get("/", (req, res, next) => {
6  return res.json({ message: "Hello, World" });
7});

Or

1Route.get("/", [UsersController, "index"]);
2
3Route.middleware(auth).get("/profile", (req, res, next) => {
4  return res.json({ message: "I'm Authenticated" });
5});

Route Group

Route groups in this framework allow for the organization and sharing of route attributes, such as middleware, across multiple routes without the need to specify them individually for each route.

1Route.prefix("/users").group((Route) => {
2  Route.get("/", UsersController.index);
3  Route.get("/create", UsersController.create);
4  Route.post("/", UsersController.store);
5  Route.get("/:id", UsersController.show);
6  Route.patch("/:id", UsersController.edit);
7  Route.delete("/:id", UsersController.destroy);
8});

Route Prefix

The prefix method adds a string to the beginning of each route name in the group. The method is used to prefix each route name in the group with "users", making it easier to identify and manage routes related to user functionality.

1Route.prefix("/users").group((Route) => {
2  Route.get("/", "index");
3  Route.get("/create", "create");
4  Route.post("/", "store");
5  Route.get("/{id}", "show");
6  Route.patch("/{id}", "edit");
7  Route.delete("/{id}", "destroy");
8});

Route Controller

If all routes in a group use the same controller, you can use the controller method to set that controller for the whole group. Then, when creating routes, you just need to specify the method they call on that controller.

1Route.controller(UsersController).group((Route) => {
2  Route.get("/", "index");
3  Route.get("/create", "create");
4  Route.post("/", "store");
5  Route.get("/{id}", "show");
6  Route.patch("/{id}", "edit");
7  Route.delete("/{id}", "destroy");
8});

Routes Parameter

In the jcc-express-mvc framework, routes often contain parameters that are dynamic values parsed from the URL path. These parameters are defined using placeholders in the route path and are accessible within route handlers via the req.params object. Routes parameters can be defined in route paths using placeholders indicated by : or {} followed by the parameter name.

1import { Route } from "jcc-express-mvc/Route";
2
3Route.get("/:id", (req, res) => {
4  console.log(req.params.id);
5});

or

1import { Route } from "jcc-express-mvc/Route";
2
3Route.get("/{id}", (req, res) => {
4  console.log(req.params.id);
5});

Controllers

The controller UsersController contains methods to handle various user-related actions.

Methods

• create(req, res, next): Renders the view for creating a new user.
• index(req, res, next): Retrieves all users from the database and renders the user index view.
• store(req, res, next): Placeholder method for storing user data.
• show(req, res, next): Renders the view for displaying a specific user.
• edit(req, res, next): Placeholder method for updating user data.
• destroy(req, res, next): Placeholder method for deleting a user. These methods encapsulate the logic for handling different user-related operations within the application.

1import { bcrypt, Auth } from "jcc-express-mvc";
2import { Request, Response, Next } from "jcc-express-mvc/core/http";
3import { User } from "@/Model/User";
4export class UsersController {
5  //
6
7  async index(req: Request, res: Response, next: Next) {
8    return res.json({
9      message: await User.all(),
10    });
11  }
12
13  //
14
15  async store(req: Request, res: Response, next: Next) {
16    await req.validate({
17      name: ["required"],
18      email: ["required", "unique:users"],
19      password: ["required", "min:6"],
20    });
21
22    const save = await User.create({
23      name: req.body.name,
24      email: req.body.email,
25      password: await bcrypt(req.body.password),
26      primary_phone: "7501035",
27    });
28
29    return save
30      ? Auth.attempt(req, res, next)
31      : res.json({ message: "Invalid credentials" });
32  }
33
34  //
35
36  async show(req: Request, res: Response, next: Next) {
37    return res.json({
38      message: await User.find(req.params.id),
39    });
40  }
41}

Middlewares

The Kernel class in app/Http/kernel.ts is responsible for managing middleware in your framework. It consists of two main properties:

• middleware: An array of globally registered middleware that runs on every request.
• middlewareAliases: An object that allows middleware to be referenced by a string alias when defining route-specific middleware.

Global Middleware

The protected middleware array contains middleware that will run on every request. Example middleware include:

1// app/Http/kernel.ts
2export class Kernel {
3    protected middleware = [
4        morgan("dev"),
5        cookieParser(),
6        cors(),
7        session({
8            secret: "ggggggg",
9            resave: false,
10            saveUninitialized: false,
11            cookie: { maxAge: 60000 },
12        }),
13        flash(),
14        fileUpload(),
15    ];
16}
17

Middleware Aliases

Middleware can be referenced by a string alias instead of passing the function directly. This makes route definitions cleaner and easier to read.

Example:

1export class Kernel {
2    protected middleware = [
3        morgan("dev"),
4        cookieParser(),
5        cors(),
6        session({
7            secret: "ggggggg",
8            resave: false,
9            saveUninitialized: false,
10            cookie: { maxAge: 60000 },
11        }),
12        flash(),
13        fileUpload(),
14    ];
15
16     static middlewareAliases = {
17        auth:auth,
18        guest:guest,
19    };
20}

Creating Custom Middleware

Middleware can be created inside the app/Http/Middlewares directory. Each middleware should be exported so it can be used in routes,registered as an alias or as a global middleware.

1// app/Http/Middlewares/AuthMiddleware.ts
2export function AuthMiddleware(req, res, next) {
3  if (!req.user) {
4    return res.status(401).json({ message: "Unauthorized" });
5  }
6  next();
7}

You can then import and use this middleware in your Kernel class or directly in routes:

1// in routes
2import { AuthMiddleware } from "@Middleware/AuthMiddleware";
3
4Route.middleware(AuthMiddleware).get("/home", (req, res, next) => {
5  return res.inertia("Home");
6});

or

1import { AuthMiddleware } from "../Http/Middlewares/AuthMiddleware";
2
3export class Kernel {
4  static middlewareAliases = {
5    authMiddleware: AuthMiddleware,
6  };
7}
8//then use it
9Route.middleware(["authMiddleware"]).get("/home", (req, res, next) => {
10  return res.inertia("Home");
11});

Using an Inline Middleware Function

Middleware can also be defined inline as a function:

1Route.middleware(function (req, res, next) {
2  console.log("Custom middleware executed");
3  next();
4}).get("/", (req, res) => {
5  return res.json({ hello: "Hello" });
6});

Summary

• Global middleware: Defined in Kernel.middleware and runs on all requests.

• Middleware aliases: Allow shorthand referencing of middleware functions in routes.

• Custom middleware: Can be created in app/Http/Middlewares and exported for use.

• Route-specific middleware: Can be applied as a string (single middleware), an array (multiple middleware), or an inline function.Summary

ORM (jcc-eloquent)

jcc-eloquent is an ORM for Node.js designed to provide Eloquent-style features and database interaction. It simplifies complex queries and supports models, relationships, mass assignment, and events

Key Features

• Model relationships: hasOne, hasMany, morphMany, etc.
• Eloquent-like mass assignment with fillable and guarded properties
• Attribute casting with casts and hidden properties for sensitive fields
• Event hooks for lifecycle methods (booted, creating, etc.)
• QueryBuilder with chainable methods like select, where, orderBy, and pagination

Basic Usage

Define models with properties like fillable, guarded, hidden, casts, and event hooks.

1import { Model } from "jcc-eloquent";
2
3class User extends Model {
4    // Attributes hidden from JSON serialization
5  protected static hidden: string[] = ["password"];
6
7  // Attributes allowed for mass assignment
8  protected static fillable: string[] = ["name"];
9
10  // Attributes excluded from mass assignment
11  protected static guarded: string[] = ["role_id"];
12
13  // Enables soft delete functionality
14  protected static softDelete: boolean = true;
15
16// Cast attributes with custom transformations
17  protected static casts = {
18      created_at: 'date', // 2024-05-23
19      created_at:'time',// 12:58
20      created_at:'datetime'// 2024-05-23 12:58
21      updated_at:'now'// 2 hours ago
22      updated_at:'date:d-m-y' // 23-05-2024
23      updated_at:'date:d/m/y' // 23/05/2024
24      getEmail: this.getEmail
25      setEmail: this.setEmail
26      id:'integer' // return the id as an integer  1;
27      price:'string' //  return the price as an string "20000"
28      draft:'array' // Will parse or stringyfy the data
29    };
30
31     // Attribute getter - retrieves email in lowercase
32    protected static getEmail(value)
33    {
34      return value.toUppercase()
35    }
36
37  // Attribute setter - sets email in uppercase
38    protected static setEmail(value)
39    {
40      return value.toLowercase()
41    }
42}

Available Relationships

1class Post extends Model {
2  author() {
3    return this.belongsTo("User", "author");
4  }
5
6  comments() {
7    return this.hasMany("Comment", "id");
8  }
9
10  likes() {
11    return this.morphyMany("likes");
12  }
13
14  //Implement custom events to hook into model actions.
15  static booted(): void {
16    this.creating((data) => {
17      // Custom logic before creating a post (e.g., setting defaults)
18    });
19
20    this.created((data) => {
21      // Custom logic after creating a post (e.g., setting defaults)
22    });
23
24    this.updating((data) => {
25      // Custom logic before updating a post (e.g., setting defaults)
26    });
27
28    this.updated((data) => {
29      // Custom logic after updating a post (e.g., setting defaults)
30    });
31
32    this.deleting((data) => {
33      // Custom logic before deleting a post (e.g., setting defaults)
34    });
35  }
36}

Querying the Database

1import { bcrypt, Auth } from "jcc-express-mvc";
2import { Request, Response, Next } from "jcc-express-mvc/core/http";
3import { Post } from "@/Model/Post";
4import { Blueprint } from "jcc-eloquent/QueryBuilder";
5export class PostsController {
6  //
7
8  async index(req: Request, res: Response, next: Next) {
9    return res.json({
10      message: await Post.with("author",{comments(query:QueryBuilder)=>query.where('status','active').with('user')
11      }).paginate(req, 100),
12    });
13  }
14
15  //
16
17  async store(req: Request, res: Response, next: Next) {
18    const attributes = await req.validate({
19      name: ["required"],
20      email: ["required", "unique:post"],
21      password: ["required", "min:6"],
22    });
23
24    const save = await Post.create({ attributes });
25    return save
26      ? Auth.attempt(req, res, next)
27      : res.json({ message: "Invalid credentials" });
28  }
29
30  //
31
32  async show(req: Request, res: Response, next: Next) {
33    return res.json({
34      message: await Post.find(req.params.id),
35    });
36  }
37}

Model.all() Retrieves all records from the database table associated with the current model.

1const users = await User.all();
2console.log(users);

Model.find(id) Retrieves a single record from the database table associated with the current model by its ID.

1const user = await User.find(1);
2console.log(user);

Model.create(data) Creates one or more records in the database table associated with the current model.

1const user = await User.create({
2  name: "John Doe",
3  email: "john.doe@example.com",
4  age: 30,
5});
6console.log(user);
7
8const users = await User.create([
9  { name: "Jane Doe", email: "jane.doe@example.com", age: 28 },
10  { name: "John Smith", email: "john.smith@example.com", age: 35 },
11]);
12console.log(users);

save() Saves the current instance to the database. If the instance has an id, it performs an update; otherwise, it performs an insert.

1const user = new User();
2user.name = "Abdou";
3await user.save();

Relationship Definitions

• hasOne(modelName, foreignKey = null, localKey = "id") Defines a one-to-one relationship between the current model and another model.

• hasMany(model, foreignKey = null, localKey = "id") Defines a one-to-many relationship between the current model and another model.

• belongsTo(modelName, foreignKey = null, localKey = "id") Defines a belongs-to relationship between the current model and another model.

Using Relationships

1import { QueryBuilder } from "jcc-eloquent/QueryBuilder";
2
3const user = await User.with("posts").get();
4const post = await Post.with({ author(query:QueryBuilder) => query.where('status', 'active') } , 'comments').get();

Query Builder Methods

The following methods are available in the query builder:

• select(...columns)
• distinct()
• from(tableName)
• where(column, operator, value)
• whereLike(column, searchValue)
• orWhere(column, operator, value)
• orderBy(column, direction)
• limit(value)
• take(value)
• offset(count)
• groupBy(...columns)
• having(column, operator, value)
• join(table, firstColumn, operator, secondColumn)
• innerJoin(table, firstColumn, operator, secondColumn)
• leftJoin(table, firstColumn, operator, secondColumn)
• rightJoin(table, firstColumn, operator, secondColumn)
• insert(data)
• get()
• update(data)
• delete(id)
• latest(column)
• oldest(column)
• with(...relations)
• each(callback)
• map(callback)
• value(field)
• exists()
• doesntExist()
• count()
• max(column)
• min(column)
• sum(column)
• avg(column)
• paginate(request, perPage)
• resetQuery()
• onlyTrashed()
• withTrashed()
• restore()

Query Instance Methods

Once you've retrieved a model instance from the database, you can interact with it using the following methods:

1. save()

Description: Saves the current instance to the database. If it's a new instance, it will perform an INSERT; if it's an existing instance, it will perform an UPDATE.

Returns: Promise<any>

Example:

1const user = await User.find(1);
2user.name = "Updated Name";
3await user.save(); // Updates the existing record

2. saveQuietly()

Description: Similar to save(), but suppresses any events that would normally be triggered during the save operation.

Returns: Promise<any>

Example:

1import { Model } from "jcc-eloquent";
2
3class Post extends Model {
4  protected static booted() {
5    this.created(async (data) => {
6      data.slug = "slug";
7      await data.saveQuietly(); // Saves without triggering any events
8    });
9  }
10}

3. load(...relations: Array<any>)

Description: Eager loads relationships on the model instance.

Returns: Promise<any>

Example:

1const user = await User.find(1);
2await user.load("posts", "comments"); // Loads posts and comments for the user

4. update()

Description: Updates the current instance in the database with the new attribute values.

Returns: Promise<any>

Example:

1const user = await User.find(1);
2user.email = "new.email@example.com";
3await user.update(); // Updates the email field in the database

5. delete()

Description: Deletes the current instance from the database.

Returns: Promise<boolean>

Example:

1const post = await Post.find(1);
2await post.delete(); // Deletes the post from the database

Query Instance Methods Overview

The following methods are part of the Query Instance used for interacting with the database:

1//Query Instance Methods
2  save() ;
3  saveQuietly();
4  load(...relations: Array<any>): ; // Eager loads relationships
5  update(); // Updates the current instance in the database
6  delete(); // Deletes the current instance from the database
7

• Methods:
  • save(): Persists the current instance to the database.
  • saveQuietly(): Saves the instance without firing any events (e.g., hooks).
  • load(): Loads specified relationships for the instance, eager loading them for optimization.
  • update(): Updates the current instance with new data.
  • delete(): Deletes the instance from the database, returning a boolean indicating success.

Schema Builder

Define database schemas with Blueprint for migrations.

1import { Schema } from "jcc-eloquent";
2
3Schema.create("users", (table) => {
4  table.id();
5  table.string("name");
6  table.unsignedBigInteger("role_id");
7  table.foreign("role_id").references("id").on("roles");
8  table.timestamps();
9});

Validation

The jcc-express-mvc framework comes with built-in validation rules that enable you to ensure the validity of data submitted by users before further processing. These validation rules can be applied either in web routes or API routes using the provided methods.

Web Validation

In web routes, you can use the req.validate() method to validate incoming data. Here's an example of how to use it:

1import { Request, Response, Next } from "jcc-express-mvc/core/http";
2
3class UsersController {
4  /**
5   *
6   *
7   * @return Express request response next
8   */
9  async store(req: Request, res: Response, next: Next) {
10    const validateData = await req.validate({
11      name: ["required"],
12      email: ["email", "unique:user"],
13      password: ["min:6"],
14    });
15
16    res.json({ validateData });
17  }
18}

• name: Specifies the name of the field to be validated.
• required: Ensures that the field is present and not empty.
• email: Validates that the field is a valid email address.
• unique:user: Checks uniqueness of the field value against a database table (e.g., checking if an email is already registered).

Api Validation

For API routes, the req.apiValidate() method is used to perform validation. Here's an example:

1async store(req:Request, res:Response, next:Next) {
2  const validateData = await req.apiValidate({
3    name: ["required"],
4    email: ["email", "unique:user"],
5    password: ["min:6"],
6  });
7
8  res.json({ validateData });
9}

validation rules

• required
• min:value
• max:value
• email
• unique:table column
• same:field name
• alpha
• alphaNum
• bool
• float
• int
• decimal
• jwt
• json
• postal
• slug
• url
• creditCard
• mongoId
• phone,
• nullable
• next

Form Request

Custom requests (or Form Requests) are useful in situations when one wants to authorize & validate a request before hitting the controller method.

1 ts-node artisanNode make:request UserRequest

example

1import { FormRequest } from "jcc-express-mvc/core/FormRequest";
2import { Request } from "jcc-express-mvc/core/http";
3
4export class UserRequest extends FormRequest {
5  constructor(req: Request) {
6    super(req);
7  }
8
9  async rules() {
10    await this.apiValidate({
11      //
12    });
13  }
14
15  async save() {
16    await this.rules();
17  }
18}

In jcc-express-mvc, the errors variable in the view file holds all the validation errors. To access errors for a specific field, use errors.field. Whereas the old variable holds all the input values.

1<form
2  action="/auth/register"
3  class="w-11/12 sm:w-[450px] py-2 px-6 bg-white"
4  method="post"
5>
6  <h2 class="text-center font-extrabold text-xl my-2 py-2">Register</h2>
7  <div class="flex-col mt-1 flex">
8    <label for="email" class="text-gray-800">Name</label>
9    <input
10      type="name"
11      placeholder="name"
12      class="outline-none border border-gray-400 mt-1 px-3 py-2"
13      id="name"
14      name="name"
15      value="{{old.name}}"
16    />
17    <small
18      class="@if(errors.name) text-red-500 text-xs mx-2 @else hidden @endif
19      >{{errors.name}}</small
20    >
21  </div>
22  <div class="flex-col mt-1 flex">
23    <label for="email" class="text-gray-800">Email</label>
24    <input
25      type="email"
26      placeholder="email"
27      class="outline-none border border-gray-400 mt-1 px-3 py-2"
28      id="email"
29      name="email"
30      value="{{old.email}}"
31    />
32    <small
33      class="@if(errors.email) text-red-500 text-xs mx-2 @else hidden @endif"
34      >{{errors.email}}</small
35    >
36  </div>
37  <div class="flex-col mt-4 flex">
38    <label for="password" class="text-gray-800">Password</label>
39    <input
40      type="password"
41      placeholder="password"
42      class="outline-none border border-gray-400 mt-1 px-3 py-2"
43      id="password"
44      name="password"
45      value=""
46    />
47    <small
48      class="@if(errors.password) text-red-500 text-xs mx-2 @else hidden @endif"
49      >{{errors.password}}</small
50    >
51  </div>
52  <div class="py-2 mt-3">
53    <button type="submit" class="bg-orange-500 p-2 w-full text-white">
54      login
55    </button>
56  </div>
57  <div class="mb-2 py-3">
58    <p class="text-sm">
59      Already have an account?
60      <a href="/login" class="text-orange-500 underline">login</a>
61    </p>
62  </div>
63</form>
64
65

Service Container & Dependency Injection

jcc-express-starter includes a Laravel-inspired service container and dependency injection system that uses reflection to automatically resolve dependencies. Defining Services javascript

Defining Services

1export class Calculator {
2  add(a: number, b: number) {
3    return a + b;
4  }
5
6  subtract(a: number, b: number) {
7    return a - b;
8  }
9}

Automatic Dependency Injection

The framework uses reflection to automatically inject dependencies into your classes. Simply define constructor parameters with the correct types:

1import { Inject } from "jcc-express-mvc/lib/Dependancy";
2import { Calculator } from "@/Services/Calculator";
3import { UserService } from "@/Services/UserService";
4
5@Inject()
6export class UserController {
7  // Dependencies are automatically injected
8  constructor(
9    private calculator: Calculator,
10    private userService: UserService
11  ) {
12
13  }
14
15}

Registering Services Manually

1import { Container } from "jcc-express-mvc/Container";
2import { ServiceProvider } from "jcc-express-mvc/lib/Services/ServiceProvider";
3import { Calculator } from "../Services/Calculator";
4import { UserService } from "../Services/UserService";
5
6export class AppServiceProvider extends ServiceProvider {
7  constructor(app: Container) {
8    super(app);
9  }
10
11  public register(): void {
12    // Register a singleton service
13    this.app.singleton<Calculator>('Calculator', new Calculator());
14
15    // Register a transient service
16  }
17
18}

Frontend

jcc-express-mvc provides robust frontend support through its jsBlade templating engine and optional Inertia.js integration, allowing you to build dynamic, reactive user interfaces.

jsBlade Templating

jcc-express-starter allows you to use any templating engine of your choice for rendering views. The package comes pre-configured with jsBlade, which is similar to Laravel's Blade templating engine. However, you can easily switch to another templating engine by configuring it in the app/Config/engine.ts file.

Configuring Templating Engine

To configure a different templating engine, follow these steps:

1. Navigate to the app/Config directory in your project.

2. Open the engine.ts file.

3. Mention .env File Configuration: Explain how users can enable the chosen templating engine by setting the TEMPLATE_ENGINE variable to true in the .env file.

4. Import the desired templating engine module. For example, if you want to use EJS, you can add the following line:

1const ejs = require("ejs");
2module.exports = (app) => {
3  app.set("view engine", "ejs");
4  return;
5};

Basic Usage

1<!-- resources/views/welcome.blade.html -->
2<html>
3  <head>
4    <title>Welcome to jcc-express-mvc</title>
5  </head>
6  <body>
7    <h1>Hello, {{ name }}</h1>
8
9    @if(items)
10    <ul>
11      @foreach(items as item)
12      <li>{{ item.name }}</li>
13      @endforeach
14    </ul>
15    @else
16    <p>No items found</p>
17    @endif
18  </body>
19</html>

Render Views from Controllers

1import { Request, Response, Next } from "jcc-express-mvc/core/http";
2
3export class HomeController {
4  async index(req: Request, res: Response, next: Next) {
5    return res.render("welcome", {
6      name: "User",
7      items: [{ name: "Item 1" }, { name: "Item 2" }, { name: "Item 3" }],
8    });
9  }
10}

Template Inheritance

jsBlade supports template inheritance, allowing you to define a base layout and extend it in child views:

Directives

jsBlade provides several directives that you can use in your views:

1@if(condition)
2<!-- Content to render if condition is true -->
3@else
4<!-- Content to render if condition is false -->
5@endif
6
7<!---->
8@ternary(condition ?
9<!--content-->
10:<!--content-->) @foreach(array as item)
11<!-- Content to render for each item in the array -->
12@endforeach
13
14<!-- layout.app.blade.html -->
15@section('content')
16<!-- Content to render in the section -->
17@endsection
18
19<!-- index.blade.html -->
20@extends('layout')
21<!--  -->
22@section('content')
23<!-- Content specific to the index view -->
24@endsection
25<!--  -->
26@auth
27<!-- Content to render for authenticated users -->
28@endauth
29<!--  -->
30@guest
31<!-- Content to render for guests (unauthenticated users) -->
32@endguest

1<!-- resources/views/layouts/app.blade.html -->
2<!DOCTYPE html>
3<html>
4  <head>
5    <title>@section('title')My App@endsection</title>
6    <link rel="stylesheet" href="/css/app.css" />
7  </head>
8  <body>
9    <header>@include('partials.nav')</header>
10
11    <main>
12      @section('content')
13      <!-- Default content -->
14      @endsection
15    </main>
16
17    <footer>@include('partials.footer')</footer>
18
19    <script src="/js/app.js"></script>
20  </body>
21</html>

1<!-- resources/views/dashboard.blade.html -->
2@extends('layouts.main') @section('title','Dashboard') @section('content')
3<div class="dashboard">
4  <h1>Dashboard</h1>
5  <p>Welcome to your dashboard!</p>
6</div>
7@endsection

Form Handling

1<form action="/users" method="POST">
2  <div class="form-group">
3    <label for="name">Name</label>
4    <input type="text" id="name" name="name" value="{{ old.name }}" />
5    @if(errors.name)
6    <small class="text-danger">{{ errors.name }}</small>
7    @endif
8  </div>
9
10  <button type="submit">Submit</button>
11</form>

Inertia.js Integration

jcc-express-mvc supports Inertia.js, enabling you to build single-page applications without the complexity of a full SPA framework.

Setup Inertia.js

1. Install required packages:

1# vue
2npm install @inertiajs/inertia @inertiajs/inertia-vue3 vue@next
3
4# react
5npm install @inertiajs/react

2. Add an Inertia middleware:

1import { inertia } from "jcc-express-mvc/inertia";
2export class Kernel {
3
4  // app/Http/kernel.ts
5  protected middleware = [
6
7    inertia({ rootView: `welcome` }),
8  ];
9
10}
11

2. Add plugin to vite:

1import { defineConfig } from "vite";
2import laravel from "laravel-vite-plugin";
3import react from "@vitejs/plugin-react";
4
5export default defineConfig({
6  plugins: [
7    laravel({
8      input: ["resources/css/text.css", "resources/js/app.js"],
9      refresh: true,
10    }),
11    // can be if vue()
12    react(),
13  ],
14});

3. Initialize the Inertia app

react

1// resources/js/app.js
2
3import { createInertiaApp } from "@inertiajs/react";
4import { createRoot } from "react-dom/client";
5
6createInertiaApp({
7  resolve: (name) => {
8    const pages = import.meta.glob("./Pages/**/*.jsx", { eager: true });
9    return pages[`./Pages/${name}.jsx`];
10  },
11  setup({ el, App, props }) {
12    createRoot(el).render(<App {...props} />);
13  },
14});

vue

1// resources/js/app.js
2
3import { createApp, h } from "vue";
4import { createInertiaApp } from "@inertiajs/vue3";
5
6createInertiaApp({
7  resolve: (name) => {
8    const pages = import.meta.glob("./Pages/**/*.vue", { eager: true });
9    return pages[`./Pages/${name}.vue`];
10  },
11  setup({ el, App, props, plugin }) {
12    createApp({ render: () => h(App, props) })
13      .use(plugin)
14      .mount(el);
15  },
16});

4. Create a base template for Inertia:

1<!-- resources/views/welcome.blade.html -->
2<!DOCTYPE html>
3<html>
4  <head>
5    <meta charset="utf-8" />
6    <meta name="viewport" content="width=device-width, initial-scale=1" />
7    <!-- For react only -->
8    @viteReactRefresh
9    <!--  -->
10    @vite(["/resources/css/text.css", "/resources/js/app.js"])
11  </head>
12  <body>
13    @inertia
14  </body>
15</html>

Using Inertia in Controllers

1import { Request, Response, Next } from "jcc-express-mvc/core/http";
2
3export class UserController {
4  async index(req: Request, res: Response, next: Next) {
5    const users = await User.all();
6
7    return res.inertia("Users/Index", {
8      users,
9    });
10  }
11}

Service providers

Service providers are the central place for binding services, configuring dependencies, and bootstrapping essential components in your framework. They allow you to define how different parts of your application are registered and initialized.

RouteServiceProvider

The RouteServiceProvider is responsible for loading routes from your application's route files. It serves as the central place to register all your application's routes.

Understanding the Route Service Provider

1import { loadRoute } from "jcc-express-mvc";
2import { ServiceProvider } from "jcc-express-mvc/core/ServiceProvider";
3
4export class RouteServiceProvider extends ServiceProvider {
5  //
6  static HOME: string = "/home";
7  //
8  constructor(app: any) {
9    super(app);
10  }
11
12  public register(): void {
13    //
14  }
15
16  public boot(): void {
17    loadRoute("api");
18    loadRoute("web");
19  }
20}

The RouteServiceProvider is located in the app/Providers directory along with other service providers like AppServiceProvider. It contains:

• HOME – constant: Defines the default route for redirects after authentication.

• booth method: Loads route files using the loadRoute() function.

Adding Custom Route Files

You can create additional route files for different sections of your application:

1. Create a new route file in the routes directory:

1// routes/admin.ts
2import { Route } from "jcc-express-mvc/Route";
3
4Route.basePath("/admin").group((Route) => {
5  Route.get("/", "index");
6  Route.get("/users", "users");
7  Route.get("/settings", "settings");
8});

2.Update the RouteServiceProvider to load the new route file:

1public boot(): void {
2  loadRoute("api");
3  loadRoute("web");
4  loadRoute("admin"); // Load the admin routes
5}

Route Organization

Organizing routes into separate files helps maintain a clean and structured codebase:

• web.ts: Routes for web pages and user-facing features

• api.ts: Routes for API endpoints

• admin.ts:Routes for administration interface

Route Loading Order

The order in which routes are loaded can be important. Routes are loaded in the sequence they appear in the boot() method. If you have overlapping routes, the last loaded route will take precedence.

1// routes/admin.ts
2import { Route } from "jcc-express-mvc/Route";
3
4Route.basePath("/admin").group((Route) => {
5  Route.get("/", "index");
6  Route.get("/users", "users");
7  Route.get("/settings", "settings");
8});

Example: Complete Route Structure

1// routes/web.ts
2import { Route } from "jcc-express-mvc/Route";
3import { HomeController } from "@Controllers/HomeController";
4
5Route.get("/", [HomeController, "index"]);
6Route.get("/about", [HomeController, "about"]);
7Route.get("/contact", [HomeController, "contact"]);
8
9// routes/api.ts
10import { Route } from "jcc-express-mvc/Route";
11import { ApiController } from "@Controllers/ApiController";
12
13Route.prefix("/api/v1").group((Route) => {
14  Route.get("/users", [ApiController, "getUsers"]);
15  Route.post("/users", [ApiController, "createUser"]);
16});
17
18// routes/admin.ts
19import { Route } from "jcc-express-mvc/Route";
20import { AdminController } from "@Controllers/AdminController";
21
22Route.basePath("/admin").group((Route) => {
23  Route.get("/", [AdminController, "dashboard"]);
24  Route.get("/users", [AdminController, "users"]);
25});
26
27// RouteServiceProvider.ts
28public boot(): void {
29  loadRoute("web");
30  loadRoute("api");
31  loadRoute("admin");
32}
33

AppServiceProviders

Responsible for registering global services and bindings needed across the application

1// app/Providers/AppServiceProviders.ts
2
3import { Container } from "jcc-express-mvc/core/Container";
4import { ServiceProvider } from "jcc-express-mvc/core/ServiceProvider";
5import {Calculator} from "../Services/CalculatorService.ts"
6import {UserService} from "../Services/UserService.ts"
7
8export class AppServiceProvider extends ServiceProvider {
9  constructor(app: Container) {
10    super(app);
11  }
12
13  public register(): void {
14    this.app.singleton<Calculator>('Calculator', new Calculator());
15    this.app.bind<UserService>('UserService', new Calculator());
16  }
17
18  public boot(): void {}
19}
20

13. Helpers

jcc-express-starter provides a set of helper functions to simplify common tasks in your Express.js applications:

• bcrypt: A async function for password hashing using bcrypt.

  1import { bcrypt } from "jcc-express-mvc";
  2const hashPass = await bcrypt("123456");
  3// Example usage

• verifyHash: A async function for verifying hashed passwords.

  1import { verifyHash } from "jcc-express-mvc";
  2const isMatch = await verifyHash("password", hashedPassword);
  3// Example usage

• authenticated: A function for implementing Passport authentication.

  1import { auth } from "jcc-express-mvc";
  2import { Route } from "jcc-express-mvc/Route";
  3
  4Route.middleware(auth).get("/profile", (req, res) => {
  5  //Access auth user's profile
  6});

• apiAuthenticated: A function for API JWT authentication. You can i get the user id with req.id

1import { ApiRoute, apiAuth } from "jcc-express-mvc";
2
3// Example usage
4ApiRoute.middleware(apiAuth).post("/api/data", (req, res) => {
5  // Access authenticated user's data
6  //req.id
7});

Str Utility

The Str utility in JCC provides various string manipulation methods inspired by Laravel’s Str helper. It simplifies common string operations, making your code cleaner and more readable.

Got it! You want to add a "Str Utility" section to your JCC framework documentation. Here’s how you can structure it:

---

Str Utility

The Str utility in JCC provides various string manipulation methods inspired by Laravel’s Str helper. It simplifies common string operations, making your code cleaner and more readable.

Usage

Import and use Str in your project:

1import { Str } from "jcc-express-mvc/core/Str";
2
3// Example usage
4console.log(Str.upper("hello")); // "HELLO"
5console.log(Str.camel("hello_world")); // "helloWorld"

Available Methods

1. Str.upper(string)

Converts a string to uppercase.

1Str.upper("hello"); // "HELLO"

2. Str.lower(string)

Converts a string to lowercase.

1Str.lower("HELLO"); // "hello"

3. Str.camel(string)

Converts a string to camelCase.

1Str.camel("hello_world"); // "helloWorld"

4. Str.snake(string)

Converts a string to snake_case.

1Str.snake("helloWorld"); // "hello_world"

5. Str.kebab(string)

Converts a string to kebab-case.

1Str.kebab("helloWorld"); // "hello-world"

6. Str.title(string)

Converts a string to title case.

1Str.title("hello world"); // "Hello World"

7. Str.random(length = 16)

Generates a random alphanumeric string of the specified length.

1Str.random(10); // "aB3dE6xYz1"

8. Str.slug(string)

Creates a URL-friendly slug from a string.

1Str.slug("Hello World!"); // "hello-world"

---

jcc-express-starter supports the jsBlade templating engine, which provides directives similar to Laravel Blade. jsBlade allows you to write expressive and clean templates for rendering views in your Express.js applications.

Usage

1. Create your view files with the .blade.html extension (or the extension specified in your template engine configuration).
2. Use jsBlade directives in your view files to write dynamic and reusable templates.

TinkerNode

TinkerNode provides an interactive command-line interface for executing JavaScript code and Mongoose queries directly in the terminal, allowing for quick testing and debugging of MongoDB interactions.

Features

• Interactive Console: TinkerNode provides an interactive console environment, similar to the Laravel Tinker, where you can execute JavaScript code and jcc-eloquent queries.

• Jcc eloquent Integration: TinkerNode seamlessly integrates with jcc-eloquent. enabling you to work with mysql databases using jcc-eloquent syntax.

1te-node artisanNode db-tinker
2
3>User.all()
4[
5  {
6    name:"John Doe",
7    email:"john@gmail.com"
8  }
9]
10