Kawkab JS

https://kawkab-docs.vercel.app
Admin
Kawkab is a modern, free, and open-source TypeScript framework for building high-performance backend...
Tokens:138,231
Snippets:762
Trust Score:7.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Basic Kawkab Controller Setup

Source: https://kawkab-docs.vercel.app/index

Demonstrates how to create a basic controller in the Kawkab framework. This example shows a simple GET method that returns a JSON response with a welcome message.

```TypeScript
import { BaseController } from "kawkab";

export default class extends BaseController
 {
    get() {
        return {
            status: true,
            message: "Welcome to Kawkab Framework 🚀!",
        }
    }
}
```

--------------------------------

### Basic Kawkab Controller Setup

Source: https://kawkab-docs.vercel.app/en

Demonstrates how to create a basic controller in the Kawkab framework. This example shows a simple GET method that returns a JSON response with a welcome message.

```TypeScript
import { BaseController } from "kawkab";

export default class extends BaseController
 {
    get() {
        return {
            status: true,
            message: "Welcome to Kawkab Framework 🚀!",
        }
    }
}
```

--------------------------------

### Documenting an Endpoint with Request and Response Examples

Source: https://kawkab-docs.vercel.app/en/digging-deeper/api-documentation

Provides an example of documenting a GET endpoint for searching products. It includes optional query parameters, pagination, success response structure, and a JSON example for the successful response.

```APIDOC
/**
 * @api {get} /products Search Products
 *
 * @apiName SearchProducts
 * @apiGroup Products
 * @apiVersion 1.0.0
 *
 * @apiParam {String} [query] Search query
 * @apiParam {Number} [page=1] Page number for pagination
 *
 * @apiSuccess {Boolean} status Operation status
 * @apiSuccess {Array} products List of products
 * @apiSuccess {String} products.name Product name
 * @apiSuccess {Number} products.price Product price
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "status": true,
 *       "products": [
 *         { "name": "Product 1", "price": 20 },
 *         { "name": "Product 2", "price": 30 }
 *       ]
 *     }
 *
 * @apiError InvalidQuery Invalid search query
 */
```

--------------------------------

### Blog Module Controller Example (TypeScript)

Source: https://kawkab-docs.vercel.app/en/getting-started/hmvc-architecture

An example controller for the blog module, demonstrating how to define a GET request handler that returns a list of blog posts. It extends a BaseController and returns a JSON object with a message and data.

```typescript
// app/modules/blog/controllers/posts/index.ts
export default class extends BaseController {
    get() {
        return {
            message: "Blog Posts",
            data: [
                { title: "First Post" },
                { title: "Second Post" }
            ]
        };
    }
}
```

--------------------------------

### Shop Module Controller Example (TypeScript)

Source: https://kawkab-docs.vercel.app/en/getting-started/hmvc-architecture

An example controller for the shop module, demonstrating how to define a GET request handler that returns a list of shop products. It extends a BaseController and returns a JSON object with a message and data.

```typescript
// app/modules/shop/controllers/products/index.ts
export default class extends BaseController {
    get() {
        return {
            message: "Shop Products",
            data: [
                { name: "Product 1" },
                { name: "Product 2" }
            ]
        };
    }
}
```

--------------------------------

### Run Application in Production Mode

Source: https://kawkab-docs.vercel.app/en/getting-started/production

This command initiates the production build of your Kawkab application, starting the server and making it accessible at the default address, typically http://localhost:3000. It ensures the application runs with its final, optimized configuration.

```bash
npm run start
```

--------------------------------

### Kawkab Controller Usage Example

Source: https://kawkab-docs.vercel.app/en/basics/controllers

An example showing how to create a controller for a specific module ('users/profile') and add logic, including middleware for GET requests. The controller is accessible via a specific API path.

```typescript
import { BaseController, inherit } from "kawkab";

export default class extends inherit(BaseController) {
    middleware() {
        return {
            get: () => {
                console.log("Middleware for Profile GET");
            },
        };
    }

    get() {
        return {
            status: true,
            message: "Welcome to Profile Page!",
        };
    }
}
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://kawkab-docs.vercel.app/en/preface/contribution-guide

Clones the project repository from a given URL and installs all necessary npm packages for development.

```shell
git clone <REPO_URL>
npm install
```

--------------------------------

### Complete Manual Transaction Example

Source: https://kawkab-docs.vercel.app/en/database/transactions

A comprehensive example demonstrating the manual transaction workflow. It includes starting a transaction, performing database operations (like saving a user), committing the transaction on success, and rolling back on error.

```typescript
import { db } from "kawkab";

const trx = await db.beginTransaction();

try {
  const user = new User;
  user.name = 'Sally';

  await user.save({
    client: trx,
  });

  await trx.commit();
} catch (e) {
  await trx.rollback();

  console.log(e.stack);
}
```

--------------------------------

### Test Organization: Setup and Grouping (TypeScript)

Source: https://kawkab-docs.vercel.app/en/security/testing

Illustrates structuring tests using `describe` blocks and `beforeEach` hooks for setup and logical grouping.

```TypeScript
describe('User Service', () => {
    // Setup before each test
    beforeEach(async () => {
        await cleanDatabase();
    });

    // Group of tests for user creation
    describe('Create User', () => {
        test('Successful creation', async () => {
            // Test code
        });

        test('Failed creation - Duplicate email', async () => {
            // Test code
        });
    });
});
```

--------------------------------

### Kawkab .env File Example

Source: https://kawkab-docs.vercel.app/en/getting-started/environment-variables

An example of an environment file (`.env`) showing how to define variables, use comments, and reference other variables for dynamic values.

```env
# Application Information
APP_NAME="Kawkab App"
APP_DEBUG=true
APP_MAINTENANCE_MODE=false

# Server Configuration
SERVER_URL=http://localhost
SERVER_PORT=3000

# Database Configuration
DATABASE_CLIENT=mysql
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=
DATABASE_NAME=kawkab

# Locale Configuration
LOCALE_CODE=en

# Mail Configuration
MAIL_HOST=sandbox.smtp.example.io
MAIL_PORT=587
MAIL_USER=
MAIL_PASS=
MAIL_TLS=false
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"
```

--------------------------------

### Example Kawkab CLI Command

Source: https://kawkab-docs.vercel.app/en/digging-deeper/data

An example demonstrating the execution of the Kawkab CLI command to create a data file named 'cats' within the default 'main' module.

```bash
npm run kawkab data:make cats
```

--------------------------------

### Kawkab Full Routing Example (TypeScript)

Source: https://kawkab-docs.vercel.app/en/getting-started/file-based-routing

A comprehensive example combining dynamic and nested routing principles for complex API endpoints. This controller handles both GET and POST requests for a path like '/api/products/:id/reviews/:reviewId', demonstrating parameter extraction for different operations.

```typescript
// app/modules/main/controllers/api/products/[id]/reviews/[reviewId].ts

import { BaseController, req } from "kawkab";

export default class extends BaseController {
    // GET /api/products/1/reviews/5
    get() {
        const { id, reviewId } = req.vars();
        return {
            productId: id,
            reviewId: reviewId,
            message: "Viewing a specific review for a specific product"
        }
    }

    // POST /api/products/1/reviews
    post() {
        const { id } = req.vars();
        return {
            message: `Adding a new review for product ${id}`
        }
    }
}
```

--------------------------------

### Start Development Server

Source: https://kawkab-docs.vercel.app/en/getting-started/installation

Launches the local development server for your Kawkab application. The application will typically be accessible at http://localhost:3000.

```bash
npm run dev
```

--------------------------------

### Example `module.ts` File Content

Source: https://kawkab-docs.vercel.app/en/getting-started/modules

Provides an example of the content for a `module.ts` file, which is central to defining a module's configuration and behavior in Kawkab. This file specifies routes, controllers, and other module-specific settings.

```typescript
import { Module } from '@kawkab/core';

export default Module({
  routes: [
    // Define module-specific routes here
  ],
  controllers: [
    // Register controllers for this module
  ],
  // Other module configurations...
});
```

--------------------------------

### Get Welcome Message Endpoint

Source: https://kawkab-docs.vercel.app/en/digging-deeper/api-documentation

Documents a GET endpoint for the welcome message. It specifies the HTTP method, path, name, group, version, success parameters, and provides a JSON success response example.

```APIDOC
/**
 * @api {get} / Get Welcome Message
 * @apiName GetWelcomeMessage
 * @apiGroup Kawkab
 * @apiVersion 1.0.0
 *
 * @apiSuccess {Boolean} status API response status.
 * @apiSuccess {String} message Kawkab framework welcome message.
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "status": true,
 *       "message": "Welcome to Kawkab Framework 🚀 - Your fast companion for building APIs with unparalleled elegance and simplicity. Let's build something extraordinary together!"
 *     }
 */
```

```javascript
import { BaseController, inherit } from "kawkab";

export default class extends inherit(BaseController) {
  /**
   * @api {get} / Get Welcome Message
   * @apiName GetWelcomeMessage
   * @apiGroup Kawkab
   * @apiVersion 1.0.0
   *
   * @apiSuccess {Boolean} status API response status.
   * @apiSuccess {String} message Kawkab framework welcome message.
   *
   * @apiSuccessExample {json} Success-Response:
   *     HTTP/1.1 200 OK
   *     {
   *       "status": true,
   *       "message": "Welcome to Kawkab Framework 🚀 - Your fast companion for building APIs with unparalleled elegance and simplicity. Let's build something extraordinary together!"
   *     }
   */
  async get() {
    return {
      status: true,
      message:
        "Welcome to Kawkab Framework 🚀 - Your fast companion for building APIs with unparalleled elegance and simplicity. Let's build something extraordinary together!",
    };
  }
}
```

--------------------------------

### Example CLI Command Execution

Source: https://kawkab-docs.vercel.app/en/digging-deeper/actions

An example of running the Kawkab CLI command to create an action named 'UpdateUserPassword' in the default 'main' module.

```shell
npm run kawkab action:make UpdateUserPassword
```

--------------------------------

### TypeScript Examples for API Versioned Controllers

Source: https://kawkab-docs.vercel.app/en/basics/api-versioning

Provides example implementations of controllers for API version 1 and version 2 using TypeScript. These examples showcase how to extend the BaseController and inherit functionality, with v2 demonstrating potential additional profile data.

```typescript
import { BaseController, inherit } from "kawkab";

export default class extends inherit(BaseController) {
    get() {
        return {
            status: true,
            version: "1.0",
            data: {
                name: "User Name",
                email: "user@example.com"
            }
        };
    }
}
```

```typescript
import { BaseController, inherit } from "kawkab";

export default class extends inherit(BaseController) {
    get() {
        return {
            status: true,
            version: "2.0",
            data: {
                name: "User Name",
                email: "user@example.com",
                profile: {
                    avatar: "https://example.com/avatar.jpg",
                    bio: "User bio"
                }
            }
        };
    }
}
```

--------------------------------

### MySQL Database Configuration

Source: https://kawkab-docs.vercel.app/en/database/configuration

Example configuration for connecting to a MySQL database using environment variables. This setup is common for Kawkab JS applications and requires defining client, host, port, user, password, and database name.

```env
DATABASE_CLIENT=mysql
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=your_password
DATABASE_NAME=your_database
```

--------------------------------

### Instantiate and Use Kawkab Action

Source: https://kawkab-docs.vercel.app/en/digging-deeper/actions

Example of creating an instance of a Kawkab Action and calling its `handle` method to execute its logic.

```javascript
const action = new UpdateUserPasswordAction();
action.handle();
```

--------------------------------

### Use Multiple Options with HTTP Requests

Source: https://kawkab-docs.vercel.app/en/digging-deeper/http

Examples showing how to apply various custom options for different HTTP methods like GET and POST, including authorization headers, timeouts, and request parameters.

```javascript
// GET request with custom options
const response = await http.get("/users", {
  headers: { "Authorization": "Bearer token" },
  timeout: 3000,
  params: { active: true },
});

// POST request with data and custom headers
const response = await http.post(
  "/login",
  { username: "ahmed", password: "123456" },
  { headers: { "Content-Type": "application/x-www-form-urlencoded" } }
);
```

--------------------------------

### Kawkab Controller with All HTTP Methods

Source: https://kawkab-docs.vercel.app/en/basics/controllers

An example of a Kawkab controller that handles all standard HTTP methods: GET, POST, PUT, PATCH, and DELETE. Each method returns a simple JSON response.

```typescript
import { BaseController, inherit } from "kawkab";

export default class extends inherit(BaseController) {
    get() {
        return { status: true, message: "This is a GET request." };
    }

    post() {
        return { status: true, message: "This is a POST request." };
    }

    put() {
        return { status: true, message: "This is a PUT request." };
    }

    patch() {
        return { status: true, message: "This is a PATCH request." };
    }

    delete() {
        return { status: true, message: "This is a DELETE request." };
    }
}
```

--------------------------------

### API Success and Error Examples

Source: https://kawkab-docs.vercel.app/en/digging-deeper/api-documentation

Demonstrates the usage of @apiSuccessExample and @apiErrorExample tags to provide structured examples of successful responses and error cases in API documentation.

```APIDOC
/**
 * @apiSuccessExample {type} title
 *    example
 *
 * @apiErrorExample {type} title
 *    example
 */
```

```APIDOC
/**
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "status": true,
 *       "data": {
 *         "id": 1,
 *         "username": "john",
 *         "email": "john@example.com"
 *       }
 *     }
 *
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "status": false,
 *       "error": "UserNotFound",
 *       "message": "User not found"
 *     }
 */
```

--------------------------------

### User Authentication Middleware Example

Source: https://kawkab-docs.vercel.app/en/basics/middleware

A practical example of an authentication middleware that checks for a token in the passed data, throwing an error if authentication fails.

```javascript
import { BaseMiddleware, inherit } from "kawkab";

export class AuthMiddleware extends BaseMiddleware {
    handle() {
        if (!this.data || !this.data.token) {
            throw new Error("Authentication failed!");
        }

        console.log("Authenticated user with token:", this.data.token);
    }
}
```

--------------------------------

### Kawkab Cron Job CLI Example

Source: https://kawkab-docs.vercel.app/en/digging-deeper/cron-jobs

An example demonstrating how to create a cron job named 'DailyTask' within the 'tasks' module using the Kawkab CLI.

```Shell
npm run kawkab cron:make DailyTask tasks
```

--------------------------------

### New Strategy Implementation Example

Source: https://kawkab-docs.vercel.app/en/digging-deeper/strategies

An example of creating an additional strategy implementation, `StrategyB`, which also conforms to the `IStrategy` interface. This showcases extensibility.

```typescript
import { IStrategy } from './IStrategy';

export class StrategyB implements IStrategy {
    execute(): void {
        console.log('Executing Strategy B...');
        // Strategy B logic
    }
}
```

--------------------------------

### Log File Content Example

Source: https://kawkab-docs.vercel.app/en/digging-deeper/logger

Presents an example of the format and content found in the `app.log` file, showing timestamps, log levels, and messages.

```text
[2024-11-28T14:32:00.000Z] [INFO] - The application started successfully.
[2024-11-28T14:33:00.000Z] [ERROR] - An error occurred in the database.
```

--------------------------------

### Kawkab HTTP Methods: GET and POST

Source: https://kawkab-docs.vercel.app/en/digging-deeper/http

Shows how to perform basic GET requests to fetch data and POST requests to send data to the server. It also illustrates accessing response data using `.data()` or `.body()`.

```javascript
// Fetch a list of users
// Using .data()
const response = await http.get("/users");
console.log(response.data());

// Or using .body()
console.log(response.body());

// Create a new user
const userData = {
  name: "Ahmed",
  email: "ahmed@example.com",
};
const postResponse = await http.post("/users", userData);
```

--------------------------------

### Cron Syntax Examples

Source: https://kawkab-docs.vercel.app/en/digging-deeper/cron-jobs

Illustrates common cron syntax patterns for scheduling tasks at different intervals, from every minute to specific days and times.

```APIDOC
Cron Syntax Fields:
1. Minute (0-59)
2. Hour (0-23)
3. Day of Month (1-31)
4. Month (1-12)
5. Day of Week (0-6, Sunday=0)

Examples:
- Every minute: "* * * * *"
- Beginning of every hour: "0 * * * *"
- Daily at 3 AM: "0 3 * * *"
- Every Sunday at 5 PM: "0 17 * * 0"
- First day of every month: "0 0 1 * *"
- Monday at 6 AM: "0 6 * * 1"
- First day of month at 12 PM: "0 12 1 * *"
```

--------------------------------

### User Registration Example

Source: https://kawkab-docs.vercel.app/en/security/hashing

Demonstrates storing a user's password securely by hashing it before saving to a database. This is a common practice for protecting user credentials.

```javascript
import { hash } from "kawkab";

async function registerUser(username: string, password: string) {
    const hashedPassword = await hash.generate(password);
    // Save the username and hashed password in the database
    console.log(`User registered: ${username}, with hashed password: ${hashedPassword}`);
}

registerUser("Hassan", "password123");
```

--------------------------------

### Integration Test Example (JavaScript/TypeScript)

Source: https://kawkab-docs.vercel.app/en/digging-deeper/test

Illustrates an integration test simulating a user registration flow, verifying the interaction between multiple components and asynchronous operations.

```javascript
describe("User Registration Flow", () => {
  let connectToDatabase: () => Promise<void>;
  let disconnectFromDatabase: () => Promise<void>;
  let registerUser: (user: {
    username: string;
    email: string;
  }) => Promise<{
    status: boolean;
    user?: { username: string; email: string };
  }>;

  beforeAll(async () => {
    // Set up database connection functions
    connectToDatabase = async () => {
      // Simulate database connection
      console.log("Database connected");
    };

    disconnectFromDatabase = async () => {
      // Simulate disconnecting from the database
      console.log("Database disconnected");
    };

    registerUser = async (user) => {
      // Simulate registration process
      if (user.username && user.email) {
        return { status: true, user };
      }
      return { status: false };
    };

    // Connect to the database
    await connectToDatabase();
  });

  afterAll(async () => {
    // Disconnect from the database
    await disconnectFromDatabase();
  });

  test("should register a new user successfully", async () => {
    const user = {
      username: "test_user",
      email: "test@example.com",
    };

    const response = await registerUser(user);
    expect(response.status).toBe(true);
    expect(response.user).toBeDefined();
    expect(response.user?.username).toBe(user.username);
    expect(response.user?.email).toBe(user.email);
  });
});
```

--------------------------------

### Initialize Kawkab Project

Source: https://kawkab-docs.vercel.app/en/getting-started/installation

Creates a new Kawkab project with all necessary configuration files. This command can be executed using either npx (Node.js) or bunx (Bun).

```bash
npx create-kawkab-app@latest init my-kawkab-app
```

```bash
bunx create-kawkab-app@latest init my-kawkab-app
```

--------------------------------

### Kawkab Base Provider Implementation

Source: https://kawkab-docs.vercel.app/en/getting-started/configuration

An example implementation of a `Provider` class extending `BaseProvider`. It includes `register` for service registration during startup and `boot` for request lifecycle initialization.

```typescript
import { BaseProvider } from "kawkab";

export class Provider extends BaseProvider {
  protected currentDir: string = __dirname;

  async register() {
    await this.modules();
  }

  boot() {
    // Initialization code for the request
  }
}
```

--------------------------------

### Database Helpers: Clean and Seed (TypeScript)

Source: https://kawkab-docs.vercel.app/en/security/testing

Utility functions for test setup and teardown, including cleaning database tables and seeding test data.

```TypeScript
// tests/helpers/database.ts
export async function cleanDatabase() {
    await db.truncate(['users', 'posts', 'comments']);
}

export async function seedTestData() {
    await db.seed(['users', 'posts']);
}
```

--------------------------------

### Example: Create 'users' Module

Source: https://kawkab-docs.vercel.app/en/getting-started/modules

Demonstrates the command to create a 'users' module and the resulting directory structure. The `module.ts` file for the 'users' module is also shown, configured with the module name 'users'.

```shell
npm run kawkab module:make users
```

```text
app/
├── users/
│   ├── controllers/
│   ├── services/
│   ├── repositories/
│   ├── dtos/
│   └── module.ts
```

```typescript
import { BaseModule } from "kawkab";

export class Module extends BaseModule {
    name(): string {
        return "users";
    }

    isEnabled(): boolean {
        return true;
    }

    register() {
        this.module(this, __dirname);
    }

    boot() {
        // Customize settings or services for the module if necessary
    }
}
```

--------------------------------

### Get Time Component with formatTime()

Source: https://kawkab-docs.vercel.app/en/digging-deeper/time

Provides an example of extracting and formatting only the time portion (hours, minutes, seconds) from a Time object using the formatTime method.

```javascript
const now = Time.now();
console.log(now.formatTime()); // Example: "14:45:30"
```

--------------------------------

### slice Method: Get Portion of Collection (JavaScript)

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Returns a portion of the collection based on the specified start index and an optional end index. The original collection is not modified.

```javascript
const sliced = collection.slice(1, 4);
console.log(sliced.all()); // [2, 3, 4]
```

--------------------------------

### Controller Example in TypeScript

Source: https://kawkab-docs.vercel.app/en/getting-started/mvc-architecture

Demonstrates a basic controller class in TypeScript that handles GET requests. It processes requests and returns a JSON response containing a message and user data.

```typescript
// app/modules/main/controllers/users/index.ts
export default class extends BaseController {
    // Handles requests and processes them
    get() {
        return {
            message: "Hello",
            data: {
                name: "Ahmed",
                email: "ahmed@example.com"
            }
        };
    }
}
```

--------------------------------

### Build Production Version

Source: https://kawkab-docs.vercel.app/en/getting-started/production

Prepares the Kawkab application for production by creating an optimized build. This command generates the final files to be deployed on the server, saving them in the .dist directory.

```bash
npm run build
```

--------------------------------

### Get String Between First Two Parts (JavaScript)

Source: https://kawkab-docs.vercel.app/en/digging-deeper/strings

Extracts the substring located between the first occurrence of a start string and the first occurrence of an end string. This is similar to `between` but explicitly emphasizes the first occurrences.

```javascript
string.betweenFirst("Hello [World] [Again]", "[", "]"); // returns: "World"
```

--------------------------------

### Get String Between Two Parts (JavaScript)

Source: https://kawkab-docs.vercel.app/en/digging-deeper/strings

Extracts the substring located between the first occurrence of a start string and the first occurrence of an end string. Returns an empty string if the delimiters are not found or in the wrong order.

```javascript
string.between("Hello [World] Again", "[", "]"); // returns: "World"
```

--------------------------------

### Importing and Using Middleware

Source: https://kawkab-docs.vercel.app/en/basics/middleware

Demonstrates how to import a middleware class and instantiate it, optionally passing data to its constructor.

```javascript
import { AuthMiddleware } from "../middleware/auth";

// Using middleware without data
new AuthMiddleware();

// Using middleware with data
new AuthMiddleware({ id: 1, name: "Hassan" });
```

--------------------------------

### Initialize Kawkab HTTP Client

Source: https://kawkab-docs.vercel.app/en/digging-deeper/http

Demonstrates how to import and initialize the Kawkab HTTP client with a base URL. This is the first step to making requests.

```javascript
import { http as Http } from "kawkab";

const http = new Http("https://api.example.com");
```

--------------------------------

### Project File Structure Example

Source: https://kawkab-docs.vercel.app/en/digging-deeper/strategies

Illustrates a recommended file structure for organizing strategies within a project module, ensuring maintainability and clarity. This structure groups related strategy files together.

```text
/strategies
  /login
    - IStrategy.ts
    - LoginStrategy.ts
    - StrategyA.ts
    - StrategyB.ts
```

--------------------------------

### Run Kawkab Repository Command

Source: https://kawkab-docs.vercel.app/en/basics/repositories

Example of executing a Kawkab CLI command to generate a new repository for a specific entity, such as 'user'. This command scaffolds the basic repository file structure.

```bash
npm run kawkab repository:make user
```

--------------------------------

### Kawkab Application Entry Point: index.ts

Source: https://kawkab-docs.vercel.app/en/concepts/application-lifecycle

This code snippet demonstrates the entry point for a Kawkab application, typically found in `index.ts`. It initializes the Kawkab framework using application configuration settings, setting up the application's core structure and behavior.

```typescript
import { kawkab } from 'kawkab'
import { app as config } from './app/configuration'

// Initialize the application using settings
export const app = kawkab.init(config)
```

--------------------------------

### Kawkab HTTP: Getting Error Details with `.toJSON()`

Source: https://kawkab-docs.vercel.app/en/digging-deeper/http

Demonstrates how to get a more detailed, stringified representation of an HTTP request error using the `.toJSON()` method.

```javascript
http.get("/user/12345").catch(function (error) {
  console.log(error.toJSON());
});
```

--------------------------------

### Advanced Folder Management Examples

Source: https://kawkab-docs.vercel.app/en/digging-deeper/folders

Illustrates practical scenarios for using Kawkab's folder operations, such as setting up project structures, archiving old data, and cleaning up empty directories.

```javascript
// Example 1: Creating a Project Structure
await Folder.create('./src/controllers');
await Folder.create('./src/models');
await Folder.create('./src/views');

// Example 2: Moving and Archiving Old Folders
const oldFolders = await Folder.list('./data/old');
for (const folder of oldFolders) {
  if (folder.endsWith('_archive')) {
    await Folder.move(`./data/old/${folder}`, './data/archived');
  }
}

// Example 3: Cleaning Empty Folders
async function cleanEmptyFolders(directory) {
  const contents = await Folder.list(directory);
  for (const item of contents) {
    const itemPath = `${directory}/${item}`;
    const stats = await Folder.stats(itemPath);
    if (stats.isDirectory()) {
      await cleanEmptyFolders(itemPath);
      const isEmpty = (await Folder.list(itemPath)).length === 0;
      if (isEmpty) {
        await Folder.remove(itemPath);
        console.log(`Removed empty folder: ${itemPath}`);
      }
    }
  }
}
await cleanEmptyFolders('./temp');
```

--------------------------------

### Create Settings File (Default Module)

Source: https://kawkab-docs.vercel.app/en/digging-deeper/settings

Command to create a new settings file in the default 'main' module. It generates a TypeScript file with example settings and provides instructions on how to import and use it.

```shell
npm run kawkab setting:make auth
```

--------------------------------

### Get HTTP Method

Source: https://kawkab-docs.vercel.app/en/basics/requests

Retrieves the HTTP method of the current request (e.g., 'GET', 'POST', 'PUT', 'DELETE'). This is essential for routing and request handling logic.

```typescript
import { request } from "kawkab";

const httpMethod = request.method();
console.log(httpMethod);
// Output: 'GET', 'POST', etc.
```

--------------------------------

### Navigate to Project Directory

Source: https://kawkab-docs.vercel.app/en/getting-started/installation

Changes the current working directory to the root of your newly created Kawkab project. This step is necessary before running development commands.

```bash
cd my-kawkab-app
```

--------------------------------

### Running Tests: Basic npm Commands (Shell)

Source: https://kawkab-docs.vercel.app/en/security/testing

Provides fundamental npm commands for executing tests, filtering by name, and enabling code coverage.

```Shell
# Run all tests
npm test

# Run specific tests
npm test users

# Run with coverage
npm test -- --coverage
```

--------------------------------

### Specific Strategy Implementation Example

Source: https://kawkab-docs.vercel.app/en/digging-deeper/strategies

An example of a concrete strategy implementation that adheres to the `IStrategy` interface. This class contains the specific algorithm logic.

```typescript
import { IStrategy } from './IStrategy';

export class StrategyA implements IStrategy {
    execute(): void {
        console.log('Executing Strategy A...');
        // Strategy logic here
    }
}
```

--------------------------------

### Running Tests (npm)

Source: https://kawkab-docs.vercel.app/en/digging-deeper/test

Provides common npm commands for executing tests, including running all tests, specific files, and using watch mode.

```bash
npm run test

npm run test -- path/to/test

npm run test -- --watch
```

--------------------------------

### inRange Function Example

Source: https://kawkab-docs.vercel.app/en/digging-deeper/numbers

Demonstrates how to use the inRange function to check if a number is within a specified range. Includes examples for numbers inside and outside the range.

```javascript
console.log(number.inRange(5, 1, 10));
// Output: true
console.log(number.inRange(15, 1, 10));
// Output: false
```

--------------------------------

### Documenting an Endpoint with Parameters

Source: https://kawkab-docs.vercel.app/en/digging-deeper/api-documentation

Shows how to document a POST endpoint for creating a new user, detailing required parameters (username, email, password) with their types and constraints, and specifying success and error responses.

```APIDOC
/**
 * @api {post} /user Create New User
 * @apiName CreateUser
 * @apiGroup Users
 * @apiVersion 1.0.0
 *
 * @apiParam {String} username Username (3-20 characters)
 * @apiParam {String} email Email address
 * @apiParam {String{6..}} password Password (minimum 6 characters)
 *
 * @apiSuccess {Boolean} status Operation status
 * @apiSuccess {Object} user Created user data
 * @apiSuccess {Number} user.id User ID
 * @apiSuccess {String} user.username Username
 * @apiSuccess {String} user.email Email address
 *
 * @apiError UserExists User already exists
 * @apiError InvalidInput Invalid input data
 */
```

--------------------------------

### Kawkab Main Application Configurations

Source: https://kawkab-docs.vercel.app/en/getting-started/configuration

Defines the main application settings, including server, database, and mail configurations, leveraging environment variables for flexibility. It aggregates all settings into a central `configuration.ts` file for easier management.

```typescript
import { env } from "kawkab";
import { Provider } from "./provider";

export const app = {
  app: {
    serverError: {
      enable: true,
      debug: env.bool("APP_DEBUG"),
      code: "server_error",
      message: env.bool("APP_DEBUG")
        ? "Server Error"
        : "An unexpected error occurred",
    },
    notFound: {
      enable: true,
      code: "not_found",
      message: "Not found",
    },
    maintenanceMode: {
      enable: env.bool("APP_MAINTENANCE_MODE"),
      message: "Service Unavailable",
    },
  },
  server: {
    port: env.number("SERVER_PORT", 3000),
    url: env.string("SERVER_URL", "http://localhost"),
  },
  database: {
    enable: true,
    client: env.get("DATABASE_CLIENT"),
    connection: {
      host: env.get("DATABASE_HOST"),
      port: env.int("DATABASE_PORT"),
      user: env.get("DATABASE_USER"),
      password: env.get("DATABASE_PASSWORD"),
      database: env.get("DATABASE_NAME"),
    },
    migrationsTableName: "migrations",
  },
  mail: {
    host: env.string("MAIL_HOST"),
    port: env.number("MAIL_PORT"),
    user: env.string("MAIL_USER"),
    password: env.string("MAIL_PASS"),
    tls: env.bool("MAIL_TLS"),
    fromAddress: env.string("MAIL_FROM_ADDRESS"),
    fromName: env.string("MAIL_FROM_NAME"),
  },
};
```

--------------------------------

### Define Attribute Accessor (Get with Attributes)

Source: https://kawkab-docs.vercel.app/en/database/mutators-casting

Defines an accessor that can use multiple model attributes to compute its value. The `get` callback receives the attribute's value and an `attributes` object containing all model attributes.

```javascript
import { BaseModel, AttributeModel } from "kawkab";

class User extends BaseModel {
  attributeFullName() {
    return AttributeModel.make({
      get: (value, attributes) => `${attributes.first_name} ${attributes.last_name}`
    })
  }
}
```

--------------------------------

### Define Attribute Accessor (Get)

Source: https://kawkab-docs.vercel.app/en/database/mutators-casting

Defines an accessor for an attribute, transforming its value upon retrieval. The `get` callback receives the attribute's value and can manipulate it. Accessors are defined as methods named `attribute{AttributeName}`.

```javascript
import { BaseModel, AttributeModel } from "kawkab";

class User extends BaseModel {
  attributeFirstName() {
    return AttributeModel.make({
      get: value => value.toUpperCase()
    })
  }
}
```

--------------------------------

### Build and Retrieve Models with Constraints

Source: https://kawkab-docs.vercel.app/en/database/models

Demonstrates building queries with constraints like `where`, `orderBy`, and `take`, then retrieving results using `get` or `first`. `get` returns a Collection, while `first` returns a single model instance.

```javascript
const flights = await Flight.query().where('active', 1)
  .orderBy('name')
  .take(10)
  .get();

const flight = await Flight.query().where('active', 1).first();
```

--------------------------------

### Integration Tests: User Login Process (TypeScript)

Source: https://kawkab-docs.vercel.app/en/security/testing

Illustrates integration tests for the user authentication service, simulating a login process and checking for success.

```TypeScript
// tests/integration/UserAuth.test.ts
describe('User Authentication', () => {
    test('Login process', async () => {
        const auth = new AuthService(new UserRepository());
        const result = await auth.login('user@example.com', 'password');
        expect(result.success).toBe(true);
    });
});
```

--------------------------------

### Access Enum Values Using Kawkab's get Method

Source: https://kawkab-docs.vercel.app/en/digging-deeper/enums

Shows how to retrieve enum values by their string name using the `get` method provided by the Kawkab Enum class. This offers a dynamic way to access enum members.

```javascript
console.log(UserType.get('Administrator'));  // Will print 0
console.log(UserType.get('Subscriber'));    // Will print 2
```

--------------------------------

### Public File Access Example

Source: https://kawkab-docs.vercel.app/en/basics/static-file-server

Illustrates how users can access public files once static file serving is enabled and configured. Files are accessed via a base URL combined with the configured public path and the specific filename.

```URL
http://localhost:3000/public/pic.jpg
```

--------------------------------

### Importing and Running Kawkab Jobs

Source: https://kawkab-docs.vercel.app/en/digging-deeper/jobs

Demonstrates how to import a Kawkab job class into your application and instantiate it, both with and without passing data to the job's `handle` method.

```TypeScript
import { SendEmailJob } from "../jobs/SendEmail";

// Method 1: Without Data
new SendEmailJob();

// Method 2: With Data
new SendEmailJob({
    to: "user@example.com",
    subject: "Hello",
    message: "Message content"
});

```

--------------------------------

### Define GET HTTP Request with kawkab

Source: https://kawkab-docs.vercel.app/en/digging-deeper/http

Demonstrates creating a custom HTTP request class extending `BaseHttp`. It shows how to define the base URL, customize the request URL using `this.data.id`, specify the GET method, set headers, and handle response data.

```typescript
import { BaseHttp, HttpMethodEnum } from "kawkab";

export class GetUserHttpRequest extends BaseHttp {
  baseUrl(): string {
    return "https://api.example.com"; // Base URL for requests
  }

  url(): string {
    // Use `this.data` to customize the URL based on the passed data
    return `/users/${this.data.id}`;
  }

  method(): HttpMethodEnum {
    return HttpMethodEnum.GET; // Request type (GET)
  }

  headers(): Record<string, string | string[]> {
    return {
      "Content-Type": "application/json", // Header settings
    };
  }

  body(): any {
    return {}; // No request body needed for GET
  }

  then(response: any) {
    return response.data; // Handle successful response
  }

  catch(error: any) {
    console.error("Error during request:", error); // Handle errors
  }

  finally() {
    console.log("Request execution completed.");
  }
}
```

--------------------------------

### Example Test Implementation with Faker (JavaScript)

Source: https://kawkab-docs.vercel.app/en/digging-deeper/faker

Shows a basic example of how to use Kawkab JS Faker within a test suite (e.g., Jest) to create mock data for testing application logic, such as user service operations.

```javascript
import { faker } from 'kawkab';

describe('User Service Tests', () => {
  it('should create a new user', async () => {
    const mockUser = {
      username: faker.internet.userName(),
      email: faker.internet.email(),
      password: faker.internet.password()
    };

    // Run your test here
  });
});
```

--------------------------------

### Create Environment Files with Kawkab CLI

Source: https://kawkab-docs.vercel.app/en/getting-started/environment-variables

This command generates environment files for development and production based on a template. It's a crucial step for setting up your project's configuration.

```bash
npm run kawkab env
```

--------------------------------

### Get Minimum Value

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Returns the minimum value found within the collection.

```javascript
const min = collection.min();
console.log(min); // 1
```

--------------------------------

### Get Median Value

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Calculates and returns the median value of the items in the collection.

```javascript
const median = collection.median();
console.log(median); // 3
```

--------------------------------

### Kawkab JS Strategy Creation

Source: https://kawkab-docs.vercel.app/en/digging-deeper/strategies

Demonstrates the command to create a new strategy in Kawkab JS, outlines the expected parameters, and shows the generated file structure including the strategy interface, main class, and an initial implementation.

```bash
kawkab make:strategy PaymentStrategy
```

```typescript
// 1. Strategy Interface (IStrategy.ts)
interface IStrategy {
  execute(): string;
}
```

```typescript
// 2. Main Strategy Class (PaymentStrategy.ts)
abstract class PaymentStrategy {
  protected strategy: IStrategy;

  constructor(strategy: IStrategy) {
    this.strategy = strategy;
  }

  public setStrategy(strategy: IStrategy) {
    this.strategy = strategy;
  }

  public executeStrategy(): string {
    return this.strategy.execute();
  }
}
```

```typescript
// 3. Specific Strategy Implementation (StrategyA.ts)
class StrategyA implements IStrategy {
  execute(): string {
    return "Executed Strategy A";
  }
}
```

--------------------------------

### Get Maximum Value

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Returns the maximum value found within the collection.

```javascript
const max = collection.max();
console.log(max); // 5
```

--------------------------------

### Create Versioned Controllers with Kawkab CLI

Source: https://kawkab-docs.vercel.app/en/basics/api-versioning

Demonstrates how to use the Kawkab CLI to generate controllers for different API versions (v1 and v2) by specifying versioned paths. This command-line interface helps in organizing API endpoints by version.

```bash
npm run kawkab controller:make users/v1/profile users
npm run kawkab controller:make users/v2/profile users
```

--------------------------------

### Get Last Collection Item

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Returns the last item present in the collection.

```javascript
const last = collection.last();
console.log(last); // 5
```

--------------------------------

### Get Item at Index

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Returns the item at the specified zero-based index `n` within the collection.

```javascript
const nth = collection.nth(2);
console.log(nth); // 3
```

--------------------------------

### Create New Module with npm

Source: https://kawkab-docs.vercel.app/en/getting-started/hmvc-architecture

Demonstrates how to create a new module using the Kawkab CLI with npm. This command scaffolds a new module directory and its basic structure.

```shell
npm run kawkab module:make blog
```

--------------------------------

### Get Collection Keys

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Returns the keys of the collection. The `all()` method can be used to retrieve all keys as an array.

```javascript
const keys = collection.keys();
console.log(keys.all()); // [0, 1, 2, 3, 4]
```

--------------------------------

### Advanced Example: Create Project Structure

Source: https://kawkab-docs.vercel.app/en/digging-deeper/folders

A function that creates a standard project directory structure (src, tests, docs, assets) and checks for existing projects.

```typescript
async function createProjectStructure(projectName: string) {
    try {
        // Check if the folder exists first
        const exists = await folder.exists(`storage/public/${projectName}`);
        if (exists) {
            throw new Error('The project already exists');
        }

        await folder.create(`storage/public/${projectName}/src`);
        await folder.create(`storage/public/${projectName}/tests`);
        await folder.create(`storage/public/${projectName}/docs`);
        await folder.create(`storage/public/${projectName}/assets`);
        console.log('Project structure created successfully');
    } catch (error) {
        console.error('Failed to create project structure:', error.message);
    }
}
```

--------------------------------

### Get Mode Values

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Returns the most frequent value(s) in the collection. If multiple values share the highest frequency, all are returned.

```javascript
const mode = collection.mode();
console.log(mode); // [1, 2, 3, 4, 5]
```

--------------------------------

### first() - Get First Item

Source: https://kawkab-docs.vercel.app/en/digging-deeper/collections

Retrieves and returns the very first item in the collection. If the collection is empty, it returns `undefined`.

```javascript
const first = collection.first();
console.log(first); // 1
```
Tokens:
Raw