├── .gitignore
├── README.md
├── middleware.js
├── next-env.d.ts
├── next.config.js
├── next.config.mjs
├── package-lock.json
├── package.json
├── pages
├── _app.jsx
├── ar
│ ├── _meta.js
│ ├── basics
│ │ ├── _meta.js
│ │ ├── api-versioning.mdx
│ │ ├── controllers.mdx
│ │ ├── events.mdx
│ │ ├── mail.mdx
│ │ ├── middleware.mdx
│ │ ├── repositories.mdx
│ │ ├── requests.mdx
│ │ ├── resources.mdx
│ │ ├── response.mdx
│ │ ├── routing.mdx
│ │ ├── service.mdx
│ │ └── static-file-server.mdx
│ ├── concepts
│ │ ├── _meta.js
│ │ ├── application-lifecycle.mdx
│ │ ├── dependency-injection.mdx
│ │ └── multiple-inheritance.mdx
│ ├── database
│ │ ├── _meta.js
│ │ ├── configuration.mdx
│ │ ├── hooks.mdx
│ │ ├── models.mdx
│ │ ├── mutators-casting.mdx
│ │ ├── pagination.mdx
│ │ ├── query-builder.mdx
│ │ ├── relationships.mdx
│ │ ├── serialization.mdx
│ │ └── transactions.mdx
│ ├── digging-deeper
│ │ ├── _meta.js
│ │ ├── actions.mdx
│ │ ├── api-documentation.mdx
│ │ ├── caching.mdx
│ │ ├── collections.mdx
│ │ ├── commands.mdx
│ │ ├── cron-jobs.mdx
│ │ ├── data.mdx
│ │ ├── dto.mdx
│ │ ├── enums.mdx
│ │ ├── factories.mdx
│ │ ├── faker.mdx
│ │ ├── files.mdx
│ │ ├── folders.mdx
│ │ ├── http.mdx
│ │ ├── jobs.mdx
│ │ ├── localization.mdx
│ │ ├── logger.mdx
│ │ ├── notifications.mdx
│ │ ├── numbers.mdx
│ │ ├── queue.mdx
│ │ ├── settings.mdx
│ │ ├── strategies.mdx
│ │ ├── strings.mdx
│ │ ├── test-driven-development.mdx
│ │ ├── test.mdx
│ │ └── time.mdx
│ ├── getting-started
│ │ ├── _meta.js
│ │ ├── architecture.mdx
│ │ ├── configuration.mdx
│ │ ├── directory-structure.mdx
│ │ ├── environment-variables.mdx
│ │ ├── file-based-routing.mdx
│ │ ├── hmvc-architecture.mdx
│ │ ├── installation.mdx
│ │ ├── modules.mdx
│ │ ├── mvc-architecture.mdx
│ │ └── production.mdx
│ ├── index.mdx
│ ├── preface
│ │ ├── _meta.js
│ │ ├── contribution-guide.mdx
│ │ ├── faqs.mdx
│ │ ├── governance.mdx
│ │ └── releases.mdx
│ └── security
│ │ ├── _meta.js
│ │ ├── auth.mdx
│ │ ├── encryption.mdx
│ │ ├── hashing.mdx
│ │ ├── input-validation.mdx
│ │ ├── password.mdx
│ │ ├── rate-limiter.mdx
│ │ └── testing.mdx
└── en
│ ├── _meta.js
│ ├── basics
│ ├── _meta.js
│ ├── api-versioning.mdx
│ ├── controllers.mdx
│ ├── events.mdx
│ ├── mail.mdx
│ ├── middleware.mdx
│ ├── repositories.mdx
│ ├── requests.mdx
│ ├── resources.mdx
│ ├── response.mdx
│ ├── routing.mdx
│ ├── service.mdx
│ └── static-file-server.mdx
│ ├── concepts
│ ├── _meta.js
│ ├── application-lifecycle.mdx
│ ├── dependency-injection.mdx
│ └── multiple-inheritance.mdx
│ ├── database
│ ├── _meta.js
│ ├── configuration.mdx
│ ├── hooks.mdx
│ ├── models.mdx
│ ├── mutators-casting.mdx
│ ├── pagination.mdx
│ ├── query-builder.mdx
│ ├── relationships.mdx
│ ├── serialization.mdx
│ └── transactions.mdx
│ ├── digging-deeper
│ ├── _meta.js
│ ├── actions.mdx
│ ├── api-documentation.mdx
│ ├── caching.mdx
│ ├── collections.mdx
│ ├── commands.mdx
│ ├── cron-jobs.mdx
│ ├── data.mdx
│ ├── dto.mdx
│ ├── enums.mdx
│ ├── factories.mdx
│ ├── faker.mdx
│ ├── files.mdx
│ ├── folders.mdx
│ ├── http.mdx
│ ├── jobs.mdx
│ ├── localization.mdx
│ ├── logger.mdx
│ ├── notifications.mdx
│ ├── numbers.mdx
│ ├── queue.mdx
│ ├── settings.mdx
│ ├── strategies.mdx
│ ├── strings.mdx
│ ├── test-driven-development.mdx
│ ├── test.mdx
│ └── time.mdx
│ ├── getting-started
│ ├── _meta.js
│ ├── architecture.mdx
│ ├── configuration.mdx
│ ├── directory-structure.mdx
│ ├── environment-variables.mdx
│ ├── file-based-routing.mdx
│ ├── hmvc-architecture.mdx
│ ├── installation.mdx
│ ├── modules.mdx
│ ├── mvc-architecture.mdx
│ └── production.mdx
│ ├── index.mdx
│ ├── preface
│ ├── _meta.js
│ ├── contribution-guide.mdx
│ ├── faqs.mdx
│ ├── governance.mdx
│ └── releases.mdx
│ └── security
│ ├── _meta.js
│ ├── auth.mdx
│ ├── encryption.mdx
│ ├── hashing.mdx
│ ├── input-validation.mdx
│ ├── password.mdx
│ ├── rate-limiter.mdx
│ └── testing.mdx
├── public
├── ar
│ ├── brands
│ │ └── tiqniaat.png
│ └── contributors
│ │ ├── 1446-05-21-22-12-00-5b2f8138.jpg
│ │ ├── 555454465656543544.png
│ │ ├── 555656543454465434544.png
│ │ ├── 556565434544.png
│ │ └── female.png
└── en
│ ├── brands
│ └── tiqniaat.png
│ └── contributors
│ ├── 1446-05-21-22-12-00-5b2f8138.jpg
│ ├── 555454465656543544.png
│ ├── 555656543454465434544.png
│ ├── 556565434544.png
│ └── female.png
├── styles.css
├── theme.config.tsx
└── tsconfig.json
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules/
2 | .env
3 | *.log
4 | dist/
5 | build/
6 | .next/
7 | .vercel
8 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Kawkab Framework
2 |
3 | A powerful Node.js/TypeScript framework for building scalable backend applications and APIs.
4 |
5 | ## Features
6 |
7 | - Built with TypeScript for type safety and better developer experience
8 | - Modular architecture for scalable applications
9 | - Environment-based configuration
10 | - CLI tool for project management
11 | - Production-ready setup
12 |
13 | ## Installation
14 |
15 | ```bash
16 | npx create-kawkab-app@latest init my-kawkab-app
17 | ```
18 |
19 | ## Quick Start
20 |
21 | 1. Clone the repository
22 | 2. Install dependencies:
23 | ```bash
24 | npm install
25 | ```
26 | 3. Copy the environment file:
27 | ```bash
28 | cp .env.example .env.development
29 | ```
30 | 4. Start development server:
31 | ```bash
32 | npm run dev
33 | ```
34 |
35 | ## Available Scripts
36 |
37 | - `npm run dev` - Start development server with hot-reload
38 | - `npm run build` - Build the project for production
39 | - `npm start` - Run the production server
40 | - `npm run remove` - Remove build directory
41 | - `npm run kawkab` - Run CLI commands
42 |
43 | ## Environment Variables
44 |
45 | The project uses different environment files for different stages:
46 | - `.env.development` - Development environment
47 | - `.env.production` - Production environment
48 | - `.env.example` - Example environment template
49 |
50 | ## Project Structure
51 |
52 | ```
53 | kawkab/
54 | ├── app/ # Application source code
55 | ├── storage/ # Storage directory
56 | ├── .dist/ # Compiled files
57 | ├── cli.ts # CLI implementation
58 | ├── index.ts # Application entry point
59 | └── tsconfig.json # TypeScript configuration
60 | ```
61 |
62 | ## Technologies
63 |
64 | - Node.js
65 | - Bun.js
66 | - TypeScript
67 |
68 | ## License
69 |
70 | This project is licensed under the MIT License - see the LICENSE file for details.
71 |
72 | ## Author
73 |
74 | Hassan Kerdash
75 |
76 | ## Keywords
77 |
78 | kawkab, framework, nodejs, bunjs, javascript, js, typescript, ts, backend, api
79 |
--------------------------------------------------------------------------------
/middleware.js:
--------------------------------------------------------------------------------
1 | export { middleware } from 'nextra/locales'
2 |
3 | export const config = {
4 | matcher: [
5 | '/((?!api|_next/static|_next/image|favicon.ico|icon.svg|apple-icon.png|manifest).*)'
6 | ]
7 | }
--------------------------------------------------------------------------------
/next-env.d.ts:
--------------------------------------------------------------------------------
1 | ///
2 | ///
3 |
4 | // NOTE: This file should not be edited
5 | // see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.
6 |
--------------------------------------------------------------------------------
/next.config.js:
--------------------------------------------------------------------------------
1 | import nextra from 'nextra'
2 |
3 | const withNextra = nextra({
4 | theme: 'nextra-theme-docs',
5 | themeConfig: './theme.config.tsx'
6 | })
7 |
8 | export default withNextra({
9 | i18n: {
10 | locales: ['en', 'ar'],
11 | defaultLocale: 'en'
12 | }
13 | })
--------------------------------------------------------------------------------
/next.config.mjs:
--------------------------------------------------------------------------------
1 | import nextra from 'nextra'
2 |
3 | const withNextra = nextra({
4 | theme: 'nextra-theme-docs',
5 | themeConfig: './theme.config.tsx'
6 | })
7 |
8 | export default withNextra({
9 | i18n: {
10 | locales: ['en', 'ar'],
11 | defaultLocale: 'en'
12 | }
13 | })
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "dependencies": {
3 | "next": "^15.0.3",
4 | "nextra": "^3.2.3",
5 | "nextra-theme-docs": "^3.2.3",
6 | "react": "^18.3.1",
7 | "react-dom": "^18.3.1"
8 | },
9 | "scripts": {
10 | "dev": "next",
11 | "build": "next build",
12 | "start": "next start"
13 | },
14 | "devDependencies": {
15 | "@types/node": "22.9.4"
16 | }
17 | }
18 |
--------------------------------------------------------------------------------
/pages/_app.jsx:
--------------------------------------------------------------------------------
1 | import "../styles.css";
2 |
3 | export default function App({ Component, pageProps }) {
4 | return ;
5 | }
6 |
--------------------------------------------------------------------------------
/pages/ar/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'index': {
3 | title: "الرئيسية",
4 | },
5 | 'preface': {
6 | title: "المقدمة",
7 | },
8 | "getting-started": {
9 | title: "البداية",
10 | },
11 | 'concepts': {
12 | title: "المفاهيم",
13 | },
14 | 'basics': {
15 | title: "الأساسية",
16 | },
17 | 'security': {
18 | title: "الأمن",
19 | },
20 | 'database': {
21 | title: "قاعدة البيانات",
22 | },
23 | 'digging-deeper': {
24 | title: "الحفر أعمق",
25 | },
26 | };
27 |
--------------------------------------------------------------------------------
/pages/ar/basics/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'routing': {
3 | title: "التوجيه",
4 | },
5 | 'controllers': {
6 | title: "المتحكمات",
7 | },
8 | 'api-versioning': {
9 | title: "إصدار واجهة برمجة التطبيقات",
10 | },
11 | "static-file-server": {
12 | title: "خادم الملفات الثابتة",
13 | },
14 | 'service': {
15 | title: "الخدمات",
16 | },
17 | 'repositories': {
18 | title: "المستودعات",
19 | },
20 | 'resources': {
21 | title: "الموارد",
22 | },
23 | 'middleware': {
24 | title: "البرمجيات الوسيطة",
25 | },
26 | 'requests': {
27 | title: "الطلبات",
28 | },
29 | 'response': {
30 | title: "الإستجابة",
31 | },
32 | 'mail': {
33 | title: "البريد الإلكتروني",
34 | },
35 | 'events': {
36 | title: 'الأحداث',
37 | },
38 | };
39 |
--------------------------------------------------------------------------------
/pages/ar/basics/api-versioning.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: إصدارات واجهة برمجة التطبيقات (API Versioning) في كوكب Kawkab
3 | description: دليل شامل لإدارة إصدارات واجهة برمجة التطبيقات (API) في إطار العمل كوكب Kawkab.
4 | ---
5 |
6 | # **إصدارات واجهة برمجة التطبيقات (API Versioning)**
7 |
8 | إدارة إصدارات واجهة برمجة التطبيقات (API Versioning) هي ممارسة مهمة في تطوير التطبيقات الحديثة. تسمح لك بتحديث واجهة برمجة التطبيقات مع الحفاظ على التوافق مع التطبيقات القديمة.
9 |
10 | ## **كيفية تنظيم الإصدارات في كوكب Kawkab**
11 |
12 | يدعم إطار العمل كوكب Kawkab إدارة إصدارات API من خلال تنظيم المتحكمات في مجلدات مختلفة لكل إصدار.
13 |
14 | ### **هيكل المجلدات المقترح:**
15 |
16 | ```
17 | app/
18 | ├── users/
19 | │ ├── controllers/
20 | │ │ ├── v1/
21 | │ │ │ └── index.ts
22 | │ │ └── v2/
23 | │ │ └── index.ts
24 | ```
25 |
26 | ## **إنشاء متحكم لإصدار معين**
27 |
28 | ### **الإصدار الأول (v1):**
29 | ```bash
30 | npm run kawkab controller:make users/v1/profile users
31 | ```
32 |
33 | ### **الإصدار الثاني (v2):**
34 | ```bash
35 | npm run kawkab controller:make users/v2/profile users
36 | ```
37 |
38 | ## **مثال على متحكمات مختلفة الإصدارات**
39 |
40 | ### **متحكم الإصدار الأول (v1):**
41 |
42 | ```ts
43 | import { BaseController, inherit } from "kawkab";
44 |
45 | export default class extends inherit(BaseController) {
46 | get() {
47 | return {
48 | status: true,
49 | version: "1.0",
50 | data: {
51 | name: "User Name",
52 | email: "user@example.com"
53 | }
54 | };
55 | }
56 | }
57 | ```
58 |
59 | ### **متحكم الإصدار الثاني (v2):**
60 |
61 | ```ts
62 | import { BaseController, inherit } from "kawkab";
63 |
64 | export default class extends inherit(BaseController) {
65 | get() {
66 | return {
67 | status: true,
68 | version: "2.0",
69 | data: {
70 | name: "User Name",
71 | email: "user@example.com",
72 | profile: {
73 | avatar: "https://example.com/avatar.jpg",
74 | bio: "User bio"
75 | }
76 | }
77 | };
78 | }
79 | }
80 | ```
81 |
82 | ## **الوصول إلى الإصدارات المختلفة**
83 |
84 | يمكن الوصول إلى الإصدارات المختلفة من خلال المسارات التالية:
85 |
86 | ### **الإصدار الأول:**
87 | ```
88 | http://localhost:3000/api/v1/users/profile
89 | ```
90 |
91 | ### **الإصدار الثاني:**
92 | ```
93 | http://localhost:3000/api/v2/users/profile
94 | ```
95 |
96 | ## **أفضل الممارسات**
97 |
98 | 1. **التوثيق الواضح:** توثيق التغييرات بين الإصدارات بشكل واضح.
99 | 2. **التوافق الخلفي:** الحفاظ على عمل الإصدارات القديمة لفترة انتقالية.
100 | 3. **إشعار التقادم:** إعلام المستخدمين عن الإصدارات التي ستصبح قديمة.
101 | 4. **تحديد مدة الدعم:** تحديد فترة دعم كل إصدار بوضوح.
102 |
103 | ## **ملخص**
104 |
105 | إدارة إصدارات API في كوكب Kawkab تتم بشكل مرن وبسيط من خلال:
106 | 1. تنظيم المتحكمات في مجلدات إصدارات.
107 | 2. دعم عدة إصدارات في نفس الوقت.
108 | 3. الحفاظ على التوافق.
109 |
--------------------------------------------------------------------------------
/pages/ar/basics/events.mdx:
--------------------------------------------------------------------------------
1 | ### الأحداث (Events) في كوكب Kawkab
2 |
3 | تعد الأحداث جزءًا أساسيًا في بناء التطبيقات الحديثة، حيث تتيح لك آلية إصدار وتنفيذ الأحداث (Event Emitters) التفاعل مع أجزاء مختلفة من التطبيق بطريقة مرنة وقابلة للتوسيع. في إطار العمل كوكب Kawkab، يمكن للمطورين إنشاء أحداث بسهولة باستخدام أوامر CLI، وهي وسيلة قوية لإضافة وظائف ديناميكية في تطبيقاتهم.
4 |
5 | #### أمر الإنشاء
6 | لإنشاء حدث جديد، يمكنك استخدام الأمر التالي:
7 |
8 | ```bash
9 | npm run kawkab event:make [module]
10 | ```
11 |
12 | - **``**: اسم الملف الذي سيتم إنشاؤه.
13 | - **``**: اسم الحدث الذي سيتم إطلاقه.
14 | - **`[module]`**: اسم الموديل (وهو اختياري، وسيتم تعيينه إلى "main" بشكل افتراضي إذا لم يتم تحديده).
15 |
16 | #### مثال:
17 | لنفترض أنك تريد إنشاء حدث يقوم بتوليد OTP (رمز تحقق) لمستخدم، يمكنك تنفيذ الأمر التالي:
18 |
19 | ```bash
20 | npm run kawkab event:make generateLoginOTP user
21 | ```
22 |
23 | #### نتيجة الملف المنشأ:
24 | سيتم إنشاء ملف جديد بالاسم `generateLoginOTP.ts` في المسار الذي يتم تحديده (`app/main/events/user/generateLoginOTP.ts`). محتويات الملف ستكون كالتالي:
25 |
26 | ```ts
27 | export default function (data: any) {
28 | console.log("Event triggered:", data);
29 | }
30 | ```
31 |
32 | #### شرح الكود:
33 | - **الوظيفة `export default function`**: هذه هي الوظيفة التي يتم تنفيذها عندما يتم إطلاق الحدث. تستقبل هذه الوظيفة بيانات (`data`) وتطبعها باستخدام `console.log`.
34 | - **`data`**: هو الكائن الذي يتم تمريره عند إطلاق الحدث، ويمكن أن يتضمن أي بيانات ترغب في معالجتها.
35 |
36 | #### كيفية استخدام الحدث:
37 | بعد إنشاء الحدث، يمكنك إطلاقه من أي مكان داخل التطبيق باستخدام الكود التالي:
38 |
39 | ```ts
40 | import { event } from "kawkab";
41 |
42 | // إطلاق الحدث
43 | event.emit('user');
44 | ```
45 |
46 | #### تمرير البيانات مع الحدث:
47 | يمكنك أيضًا تمرير البيانات مع الحدث باستخدام الكود التالي:
48 |
49 | ```ts
50 | event.emit('user', { otp: '123456', userId: 1 });
51 | ```
52 |
53 | #### خاتمة:
54 | الأحداث هي طريقة قوية لتنظيم العمل في تطبيقاتك، حيث تسمح بتفاعل مرن بين مختلف أجزاء النظام. مع Kawkab، أصبحت عملية إنشاء وإدارة الأحداث سهلة ومرنة، مما يساعدك في بناء تطبيقات قوية وأكثر تفاعلية.
--------------------------------------------------------------------------------
/pages/ar/basics/repositories.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: إدارة المستودعات (Repositories) في كوكب Kawkab
3 | description: دليل إنشاء واستخدام المستودعات (Repositories) في إطار العمل كوكب Kawkab لتنظيم التعامل مع قواعد البيانات.
4 | ---
5 |
6 | # إدارة المستودعات (Repositories) في كوكب Kawkab
7 |
8 | المستودعات (Repositories) هي مكون أساسي في إطار العمل **كوكب Kawkab** تُستخدم لفصل منطق الوصول إلى البيانات عن الخدمات (Services) وبقية التطبيق. يتيح لك هذا الأسلوب تنظيم العمليات المرتبطة بقاعدة البيانات وجعل الكود أكثر نظافة وقابلية لإعادة الاستخدام.
9 |
10 | ---
11 |
12 | ## أمر إنشاء مستودع
13 |
14 | لإنشاء مستودع جديد، استخدم الأمر التالي:
15 |
16 | ```bash
17 | npm run kawkab repository:make [module]
18 | ```
19 |
20 | ### **المعلمات:**
21 | - ``: اسم المستودع المراد إنشاؤه (مثل: `user`).
22 | - `[module]` _(اختياري)_: اسم الوحدة التي ينتمي إليها المستودع. إذا لم يتم تحديد وحدة، سيتم وضعه في الوحدة الافتراضية `main`.
23 |
24 | ### **مثال:**
25 | ```bash
26 | npm run kawkab repository:make user
27 | ```
28 |
29 | ---
30 |
31 | ## الهيكل الأساسي لملف المستودع
32 |
33 | عند إنشاء مستودع جديد، سيتم إنشاء ملف يحتوي على الهيكل التالي مثل:
34 |
35 | ```typescript
36 | import { BaseRepository, Inject, inherit } from "kawkab";
37 | import { User } from "../models/user";
38 |
39 | export class UserRepository extends inherit(BaseRepository, Inject) {
40 | findById(id: number) {
41 | return User.query().find(id);
42 | }
43 | }
44 | ```
45 |
46 | ### **شرح الكود:**
47 | 1. **BaseRepository**: الفئة الأساسية التي تحتوي على الوظائف الافتراضية للعمل مع قواعد البيانات.
48 | 2. **Inject**: تُستخدم لإدارة الاعتماديات (Dependency Injection).
49 | 3. **inherit**: تُستخدم لدمج الوظائف من الفئات الأساسية.
50 | 4. **`findById`**: مثال على طريقة مخصصة للعثور على مستخدم بناءً على المعرف (ID).
51 |
52 | ---
53 |
54 | ## استخدام المستودع داخل خدمة
55 |
56 | بعد إنشاء المستودع، يمكن استيراده واستخدامه داخل الخدمات (Services). إليك مثالًا على ذلك:
57 |
58 | ```typescript
59 | import { BaseService, Inject, inherit } from "kawkab";
60 | import { UserRepository } from "../repositories/user";
61 |
62 | export class UserService extends inherit(BaseService, Inject) {
63 | constructor(private userRepository = UserRepository.inject()) {
64 | super();
65 | }
66 |
67 | findById(id: number) {
68 | return this.userRepository.findById(id);
69 | }
70 | }
71 | ```
72 |
73 | ### **شرح الكود:**
74 | 1. **`UserRepository.inject()`**: يتم حقن المستودع تلقائيًا لاستخدامه داخل الخدمة.
75 | 2. **`findById`**: خدمة تستدعي وظيفة `findById` في المستودع لتنفيذ منطق قاعدة البيانات.
76 |
77 | ---
78 |
79 | ## فوائد استخدام المستودعات
80 |
81 | 1. **فصل منطق قاعدة البيانات**: يسهل فصل منطق الوصول إلى البيانات عن بقية التطبيق.
82 | 2. **إعادة استخدام الكود**: يمكن استخدام المستودعات عبر خدمات متعددة.
83 | 3. **اختبارات أسهل**: تسهل المستودعات اختبار الكود بفضل فصل منطق البيانات.
84 | 4. **تنظيم الكود**: تجعل الكود أكثر ترتيبًا وقابلية للتوسع.
85 |
86 | ---
87 |
88 | ## الخاتمة
89 |
90 | باستخدام المستودعات (Repositories) في **كوكب Kawkab**، يمكنك إدارة منطق قاعدة البيانات بشكل أفضل وتحقيق هيكل أكثر تنظيمًا لتطبيقك.
91 |
92 | 🎉 **ابدأ الآن بإنشاء مستودعات مذهلة في إطار عمل كوكب Kawkab!**
--------------------------------------------------------------------------------
/pages/ar/basics/resources.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: إدارة الموارد (Resources) في كوكب Kawkab
3 | description: دليل إنشاء واستخدام الموارد (Resources) لتنسيق بيانات الاستجابات في إطار العمل كوكب Kawkab.
4 | ---
5 |
6 | # إدارة الموارد (Resources) في كوكب Kawkab
7 |
8 | الموارد (Resources) هي طبقة إضافية في إطار العمل **كوكب Kawkab** تُستخدم لتنسيق البيانات المرسلة إلى العميل. تساعد الموارد في توحيد تنسيق الاستجابات وجعل الكود أكثر تنظيماً وقابلية للصيانة.
9 |
10 | ---
11 |
12 | ## أمر إنشاء مورد
13 |
14 | لإنشاء مورد جديد، استخدم الأمر التالي:
15 |
16 | ```bash
17 | npm run kawkab resource:make [module]
18 | ```
19 |
20 | ### **المعلمات:**
21 | - ``: اسم المورد المراد إنشاؤه (مثل: `user`).
22 | - `[module]` _(اختياري)_: اسم الوحدة التي ينتمي إليها المورد. إذا لم يتم تحديد وحدة، سيتم وضعه في الوحدة الافتراضية `main`.
23 |
24 | ### **مثال:**
25 | ```bash
26 | npm run kawkab resource:make user
27 | ```
28 |
29 | ### **الإخراج:**
30 | ```plaintext
31 | 🆗 Resource user created successfully in module main.
32 | 1️⃣ Your resource is ready! You can now import it like this:
33 |
34 | 👉 import { UserResource } from '../resources/user'
35 |
36 | 2️⃣ Use the resource like so:
37 | 👉 const users = await Users.query().get();
38 | 👉 return { status: true, users: UserResource.collect(users) };
39 | ```
40 |
41 | ---
42 |
43 | ## الهيكل الأساسي لملف المورد
44 |
45 | عند إنشاء مورد جديد، سيتم إنشاء ملف يحتوي على الهيكل التالي:
46 |
47 | ```typescript
48 | import { BaseResource } from "kawkab";
49 |
50 | export class UserResource extends BaseResource {
51 | public resource() {
52 | return {
53 | id: this.data.id,
54 | name: this.data.name
55 | };
56 | }
57 | }
58 | ```
59 |
60 | ### **شرح الكود:**
61 | 1. **BaseResource**: الفئة الأساسية التي تُستخدم لتنسيق البيانات.
62 | 2. **`resource`**: دالة تُستخدم لتحديد تنسيق البيانات المرسلة إلى العميل.
63 | 3. **`this.data`**: تمثل البيانات المُمررة إلى المورد.
64 |
65 | ---
66 |
67 | ## استخدام المورد
68 |
69 | يمكن استخدام الموارد لتنسيق البيانات قبل إعادتها إلى العميل. إليك مثالًا:
70 |
71 | ```typescript
72 | import { BaseController, inherit } from "kawkab";
73 | import { UserResource } from "../resources/user";
74 |
75 | export default class extends inherit(BaseController) {
76 | async get() {
77 | const users = await Users.query().get();
78 | return {
79 | status: true,
80 | users: UserResource.collect(users)
81 | };
82 | }
83 | }
84 | ```
85 |
86 | ### **شرح الكود:**
87 | 1. **`UserResource.collect(users)`**: تقوم بتنسيق مجموعة من العناصر باستخدام المورد.
88 | 2. **`users`**: تمثل البيانات المستردة من قاعدة البيانات.
89 | 3. **`return`**: تُعيد الاستجابة بتنسيق مُنسق باستخدام المورد.
90 |
91 | ---
92 |
93 | ## فوائد استخدام الموارد
94 |
95 | 1. **تنسيق البيانات**: تجعل الاستجابات موحدة وسهلة الفهم.
96 | 2. **إعادة استخدام الكود**: يمكن استخدام الموارد لتنسيق البيانات عبر وحدات متعددة.
97 | 3. **تحسين الأمان**: تتيح لك التحكم في البيانات التي يتم إرسالها إلى العميل.
98 | 4. **تنظيم الكود**: تفصل بين منطق معالجة البيانات ومنطق عرضها.
99 |
100 | ---
101 |
102 | ## النتيجة
103 |
104 | الموارد (Resources) في **كوكب Kawkab** تساعدك في تحسين تجربة تطوير واجهات برمجية منظمة وقابلة للصيانة.
105 |
106 | 🎉 **ابدأ الآن بتنظيم استجاباتك مع الموارد في إطار عمل كوكب Kawkab!**
--------------------------------------------------------------------------------
/pages/ar/basics/service.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: إدارة الخدمات في كوكب Kawkab
3 | description: دليل إنشاء واستخدام الخدمات (Services) في إطار العمل كوكب Kawkab لتنظيم منطق العمل وإعادة استخدامه.
4 | ---
5 |
6 | # إدارة الخدمات في كوكب Kawkab
7 |
8 | الخدمات (Services) هي مكونات في إطار العمل **كوكب Kawkab** تُستخدم لتنظيم المنطق الأساسي لتطبيقك بطريقة قابلة لإعادة الاستخدام. تتيح لك الخدمات تجميع الوظائف الشائعة وإعادة استخدامها بسهولة داخل وحدات التحكم (Controllers) أو مكونات أخرى.
9 |
10 | ---
11 |
12 | ## أمر إنشاء خدمة
13 |
14 | لإنشاء خدمة جديدة، يمكنك استخدام الأمر التالي:
15 |
16 | ```bash
17 | npm run kawkab service:make [module]
18 | ```
19 |
20 | ### **المعلمات:**
21 | - ``: اسم الخدمة المراد إنشاؤها (مثل: `login`).
22 | - `[module]` _(اختياري)_: اسم الوحدة التي تنتمي إليها الخدمة. إذا لم يتم تحديد وحدة، سيتم وضعها ضمن الوحدة الافتراضية `main`.
23 |
24 | ### **مثال:**
25 | ```bash
26 | npm run kawkab service:make login
27 | ```
28 |
29 | ---
30 |
31 | ## الهيكل الأساسي لملف الخدمة
32 |
33 | عند إنشاء خدمة جديدة، سيتم إنشاء ملف يحتوي على الهيكل التالي مثل:
34 |
35 | ```typescript
36 | import { BaseService, Inject, inherit } from "kawkab";
37 |
38 | export class LoginService extends inherit(BaseService, Inject) {
39 | login() {
40 | console.log("Login Service!");
41 | }
42 | }
43 | ```
44 |
45 | ### **شرح الكود:**
46 | 1. **BaseService**: فئة أساسية توفر وظائف افتراضية يمكن أن تستفيد منها الخدمات.
47 | 2. **Inject**: تُستخدم لإدارة الاعتماديات (Dependency Injection).
48 | 3. **inherit**: تُستخدم لدمج الوظائف من الفئات الأساسية.
49 | 4. **LoginService**: مثال على خدمة تحتوي على طريقة `login` بسيطة تطبع رسالة إلى وحدة التحكم.
50 |
51 | ---
52 |
53 | ## استخدام الخدمة داخل وحدة تحكم
54 |
55 | بعد إنشاء الخدمة، يمكن استيرادها واستخدامها في وحدات التحكم (Controllers). إليك مثالًا على كيفية القيام بذلك:
56 |
57 | ```typescript
58 | import { BaseController, inherit } from "kawkab";
59 | import { LoginService } from "../services/login";
60 |
61 | export default class extends inherit(BaseController) {
62 | constructor(private loginService = LoginService.inject()) {
63 | super();
64 | }
65 |
66 | async post() {
67 | this.loginService.login();
68 |
69 | return {
70 | status: true,
71 | message: "Login Successful",
72 | }
73 | }
74 | }
75 | ```
76 |
77 | ### **شرح الكود:**
78 | 1. **`LoginService.inject()`**: يتم حقن الخدمة تلقائيًا لاستخدامها داخل وحدة التحكم.
79 | 3. **`post`**: يستخدم طريقة `login` من الخدمة وينفذ منطق تسجيل الدخول.
80 |
81 | ---
82 |
83 | ## فوائد استخدام الخدمات
84 |
85 | 1. **إعادة استخدام الكود**: يمكنك استخدام الخدمات عبر وحدات متعددة دون تكرار المنطق.
86 | 2. **تقسيم المسؤوليات**: تفصل الخدمات بين منطق العمل الأساسي ووحدات التحكم.
87 | 3. **مرونة الصيانة**: يسهل تحديث الخدمات بشكل مستقل دون التأثير على بقية التطبيق.
88 | 4. **إدارة الاعتماديات**: يدعم إطار العمل Kawkab إدارة الاعتماديات بسهولة باستخدام `Inject`.
89 |
90 | ---
91 |
92 | ## الخاتمة
93 |
94 | باستخدام **كوكب Kawkab**، تصبح إدارة الخدمات وتنظيم الكود أكثر سهولة وفعالية. توفر الخدمات طريقة قوية لإدارة منطق العمل، مما يجعل تطبيقك أكثر تنظيمًا وقابلية للتطوير.
95 |
96 | 🎉 **ابدأ الآن ببناء خدمات مذهلة في إطار عمل كوكب Kawkab!**
--------------------------------------------------------------------------------
/pages/ar/concepts/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'application-lifecycle': {
3 | title: 'دورة الحياة',
4 | },
5 | 'multiple-inheritance': {
6 | title: 'الوراثة المتعددة',
7 | },
8 | 'dependency-injection': {
9 | title: 'حقن التبعية',
10 | },
11 | }
--------------------------------------------------------------------------------
/pages/ar/concepts/application-lifecycle.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: دورة حياة التطبيق في كوكب Kawkab
3 | description: دليل شامل لفهم دورة حياة التطبيق في إطار العمل كوكب Kawkab وكيفية تهيئته وإدارته.
4 | ---
5 |
6 | # **دورة حياة التطبيق في كوكب Kawkab**
7 |
8 | إطار العمل **كوكب Kawkab** يعتمد على مفهوم دورة حياة التطبيق (**Application Lifecycle**) لإدارة تهيئة التطبيق واستقبال الطلبات بطريقة منظمة. تبدأ دورة حياة التطبيق من نقطة التهيئة وتنتقل إلى استقبال ومعالجة كل طلب.
9 |
10 | ---
11 |
12 | ## **تهيئة التطبيق (Initialization)**
13 |
14 | ### **1. نقطة البداية: `index.ts`**
15 | الملف `index.ts` هو نقطة البداية لتطبيق **كوكب Kawkab**. يقوم باستيراد الإطار وتهيئة التطبيق بناءً على الإعدادات المعرفة مسبقًا.
16 |
17 | ```ts
18 | import { kawkab } from 'kawkab'
19 | import { app as config } from './app/configuration'
20 |
21 | // تهيئة التطبيق باستخدام الإعدادات
22 | export const app = kawkab.init(config)
23 | ```
24 |
25 | ### **2. ملف الإعدادات: `configuration.ts`**
26 | هذا الملف يحتوي على الإعدادات اللازمة لتشغيل التطبيق. يعتمد التطبيق على **مزود الخدمة (Provider)** الذي يتولى مسؤولية تسجيل الوحدات (Modules) وتهيئتها.
27 |
28 | ```ts
29 | import { Provider } from './provider'
30 |
31 | export const app = {
32 | provider: Provider,
33 | }
34 | ```
35 |
36 | ---
37 |
38 | ## **مزود الخدمة (Provider)**
39 |
40 | ### **دور مزود الخدمة**
41 | المزود هو المسؤول عن تسجيل الوحدات (**Modules**) اللازمة للتطبيق وتقديم التهيئة المطلوبة. يتم تنفيذه من خلال فئة (`Class`) موروثة من `BaseProvider`.
42 |
43 | ```ts
44 | import { BaseProvider } from "kawkab"
45 |
46 | export class Provider extends BaseProvider {
47 | /**
48 | * المسار الحالي للمزود
49 | * يتم استخدامه للحصول على مسار الدليل الحالي.
50 | */
51 | protected currentDir: string = __dirname
52 |
53 | /**
54 | * تسجيل الوحدات
55 | * يتم استدعاء هذه الدالة مرة واحدة عند بدء تشغيل التطبيق.
56 | * تسجل وتُهيئ الوحدات اللازمة للتطبيق.
57 | */
58 | async register() {
59 | await this.modules()
60 | }
61 |
62 | /**
63 | * الإعداد مع كل طلب
64 | * يتم استدعاء هذه الدالة مع كل طلب جديد.
65 | * تُستخدم لتسجيل الإعدادات أو الخدمات الإضافية.
66 | */
67 | boot() {
68 | // قم بكتابة التعليمات البرمجية هنا
69 | }
70 | }
71 | ```
72 |
73 | ### **دورة حياة المزود**
74 | 1. **Register**:
75 | يتم استدعاؤها مرة واحدة فقط عند بدء تشغيل الخادم. تُستخدم لتسجيل الوحدات (Modules) وإجراء التهيئات اللازمة.
76 |
77 | 2. **Boot**:
78 | يتم استدعاؤها مع كل طلب جديد لمعالجة الإعدادات الديناميكية أو خدمات الطلب.
79 |
80 | ---
81 |
82 | ## **توضيح دورة حياة التطبيق**
83 |
84 | 1. **تهيئة الإطار:**
85 | - يبدأ الإطار عند استدعاء `kawkab.init()` في ملف `index.ts`.
86 | - يتم استيراد إعدادات التطبيق من `configuration.ts`.
87 |
88 | 2. **تسجيل الوحدات:**
89 | - يقوم المزود باستدعاء `register()` لتسجيل الوحدات اللازمة للتطبيق.
90 |
91 | 3. **معالجة الطلبات:**
92 | - يتم استدعاء `boot()` مع كل طلب جديد لتقديم خدمات إضافية أو إعادة تهيئة.
93 |
94 | ---
95 |
96 | ## **الخلاصة**
97 |
98 | يوفر إطار العمل **كوكب Kawkab** دورة حياة واضحة ومُنظمة للتطبيق، مما يتيح للمطورين إمكانية إدارة تسجيل الوحدات وتهيئتها بطريقة سلسة. باستخدام `Provider`، يمكن تخصيص التهيئة وضمان أداء عالي للتطبيق عند التعامل مع الطلبات.
--------------------------------------------------------------------------------
/pages/ar/database/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | "configuration": {
3 | title: "التكوينات",
4 | },
5 | "query-builder": {
6 | title: "منشئ الاستعلامات",
7 | },
8 | "models": {
9 | title: "النماذج",
10 | },
11 | "relationships": {
12 | title: "العلاقات",
13 | },
14 | "pagination": {
15 | title: "تعدد الصفحات",
16 | },
17 | "mutators-casting": {
18 | title: "المحولات",
19 | },
20 | "hooks": {
21 | title: "الخطافات",
22 | },
23 | "transactions": {
24 | title: "المعاملات",
25 | },
26 | "serialization": {
27 | title: "التحويلات",
28 | },
29 | };
30 |
--------------------------------------------------------------------------------
/pages/ar/database/configuration.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: إعداد قواعد البيانات
3 | description: دليل شامل لإعداد وتكوين قواعد البيانات المدعومة في إطار العمل كوكب
4 | ---
5 |
6 | # إعداد قواعد البيانات
7 |
8 | ## نظرة عامة
9 |
10 | يدعم كوكب العديد من أنظمة إدارة قواعد البيانات الشائعة. يمكنك تكوين إعدادات قاعدة البيانات من خلال ملف `.env` في مجلد المشروع الرئيسي.
11 |
12 | ## قواعد البيانات المدعومة
13 |
14 | ### MySQL
15 | نظام قواعد البيانات العلائقية الأكثر شعبية، مناسب للتطبيقات الصغيرة والمتوسطة.
16 |
17 | ```env
18 | DATABASE_CLIENT=mysql
19 | DATABASE_HOST=127.0.0.1
20 | DATABASE_PORT=3306
21 | DATABASE_USER=root
22 | DATABASE_PASSWORD=your_password
23 | DATABASE_NAME=your_database
24 | ```
25 |
26 | #### مميزات MySQL
27 | - سهولة الاستخدام والإعداد
28 | - أداء جيد للقراءة
29 | - دعم مجتمعي واسع
30 | - مناسب للتطبيقات الويب التقليدية
31 |
32 | ### PostgreSQL
33 | نظام قواعد بيانات متقدم مع ميزات إضافية، مثالي للتطبيقات المعقدة.
34 |
35 | ```env
36 | DATABASE_CLIENT=pgsql
37 | DATABASE_HOST=127.0.0.1
38 | DATABASE_PORT=5432
39 | DATABASE_USER=postgres
40 | DATABASE_PASSWORD=your_password
41 | DATABASE_NAME=your_database
42 | ```
43 |
44 | #### مميزات PostgreSQL
45 | - دعم للأنواع المتقدمة من البيانات
46 | - قدرات بحث نصي متقدمة
47 | - تعامل أفضل مع التزامن
48 | - مناسب للتطبيقات المؤسسية
49 |
50 | ### SQLite
51 | قاعدة بيانات خفيفة تعمل كملف واحد، مثالية للتطوير والتطبيقات الصغيرة.
52 |
53 | ```env
54 | DATABASE_CLIENT=sqlite
55 | DATABASE_NAME=database/database.sqlite
56 | ```
57 |
58 | #### مميزات SQLite
59 | - لا تحتاج لخادم منفصل
60 | - سهولة النقل والنسخ الاحتياطي
61 | - مثالية للتطوير والاختبار
62 | - مناسبة للتطبيقات المحمولة
63 |
64 | ## إعدادات الاتصال
65 |
66 | ### الإعدادات الأساسية
67 |
68 | ```env
69 | # نوع قاعدة البيانات
70 | DATABASE_CLIENT=mysql
71 |
72 | # معلومات الاتصال
73 | DATABASE_HOST=127.0.0.1
74 | DATABASE_PORT=3306
75 | DATABASE_USER=root
76 | DATABASE_PASSWORD=your_password
77 | DATABASE_NAME=your_database
78 | ```
79 |
80 | ### شرح الإعدادات
81 |
82 | | الإعداد | الوصف | القيم المحتملة |
83 | |---------|--------|----------------|
84 | | `DATABASE_CLIENT` | نوع قاعدة البيانات | `mysql`, `pgsql`, `sqlite` |
85 | | `DATABASE_HOST` | عنوان الخادم | IP أو اسم النطاق |
86 | | `DATABASE_PORT` | منفذ الاتصال | رقم المنفذ |
87 | | `DATABASE_USER` | اسم المستخدم | نص |
88 | | `DATABASE_PASSWORD` | كلمة المرور | نص |
89 | | `DATABASE_NAME` | اسم قاعدة البيانات | نص |
90 |
91 | ## أفضل الممارسات
92 |
93 | ### 1. الأمان
94 | - لا تخزن كلمات المرور في نظام التحكم بالإصدار
95 | - استخدم مستخدم قاعدة بيانات بصلاحيات محدودة
96 | - قم بتشفير الاتصال في البيئة الإنتاجية
97 |
98 | ### 2. الأداء
99 | - اضبط حجم تجمع الاتصالات حسب احتياجات تطبيقك
100 | - استخدم الفهارس بشكل مناسب
101 | - راقب أداء الاستعلامات
102 |
103 | ### 3. النسخ الاحتياطي
104 | - قم بإعداد نسخ احتياطي منتظم
105 | - اختبر عملية استعادة النسخ الاحتياطي
106 | - احتفظ بنسخ في مواقع مختلفة
107 |
108 | ## حل المشكلات الشائعة
109 |
110 | ### مشكلة الاتصال
111 | ```bash
112 | # تأكد من تشغيل خادم قاعدة البيانات
113 | sudo service mysql status
114 |
115 | # تحقق من صحة بيانات الاتصال
116 | mysql -u root -p
117 | ```
118 |
119 | ### مشكلة الصلاحيات
120 | ```sql
121 | -- منح الصلاحيات للمستخدم
122 | GRANT ALL PRIVILEGES ON database_name.* TO 'user'@'localhost';
123 | FLUSH PRIVILEGES;
124 | ```
125 |
126 | ## الخاتمة
127 |
128 | إعداد قاعدة البيانات في كوكب:
129 | - مرن ويدعم عدة أنظمة
130 | - سهل التكوين عبر ملف `.env`
131 | - قابل للتخصيص حسب احتياجات المشروع
132 |
133 | نصائح نهائية:
134 | - اختر نوع قاعدة البيانات المناسب لمشروعك
135 | - اتبع أفضل ممارسات الأمان
136 | - قم بتوثيق إعدادات قاعدة البيانات
137 | - احتفظ بنسخ احتياطية منتظمة
138 |
--------------------------------------------------------------------------------
/pages/ar/database/hooks.mdx:
--------------------------------------------------------------------------------
1 | # الخطافات
2 |
3 | تطلق نماذج Kawkab عدة أحداث، مما يتيح لك الربط في اللحظات التالية في دورة حياة النموذج: `creating`، `created`، `updating`، `updated`، `saving`، `saved`، `deleting`، `deleted`، `restoring`، `restored`، `trashed`، `forceDeleting` و `forceDeleted`.
4 |
5 | يتم إطلاق أسماء الأحداث التي تنتهي بـ `-ing` قبل أن يتم حفظ أي تغييرات على النموذج، بينما يتم إطلاق الأحداث التي تنتهي بـ `-ed` بعد أن يتم حفظ التغييرات على النموذج.
6 |
7 | ### الخطافات المتاحة
8 |
9 | | الخطاف | الوصف |
10 | | -------------------------------- | ----------------------------------------------------------------------------------------- |
11 | | `creating`, `created` | عند حفظ نموذج جديد لأول مرة |
12 | | `updating`, `updated` | عند تعديل نموذج موجود واستدعاء طريقة `save` |
13 | | `saving`, `saved` | عند إنشاء أو تحديث نموذج - حتى إذا لم تتغير خصائص النموذج |
14 | | `deleting`, `deleted` | عند حذف نموذج، بما في ذلك الحذف الناعم |
15 | | `restoring`, `restored` | عند استعادة نموذج |
16 | | `trashed` | عند حذف نموذج حذفًا ناعمًا |
17 | | `forceDeleteing`, `forceDeleted` | عند حذف نموذج حذفًا نهائيًا |
18 |
19 | :::tip عند إصدار استعلام تحديث أو حذف جماعي عبر Kawkab، لن يتم إطلاق أحداث النموذج `saved`، `updated`، `deleting`، و `deleted` للنماذج المتأثرة. هذا لأن النماذج لا يتم استرجاعها فعليًا عند تنفيذ التحديثات أو الحذف الجماعي. :::
20 |
21 | ### إعلان الخطافات
22 |
23 | هناك حاليًا طريقتان لإضافة الخطافات برمجيًا:
24 |
25 | ```js
26 | class User extends Model {}
27 |
28 | User.creating(user => {
29 | //
30 | });
31 | ```
32 |
33 | ```js
34 | class User {
35 | static booted() {
36 | this.creating(user => {
37 | //
38 | });
39 |
40 | this.created(user => {
41 | //
42 | });
43 | }
44 | }
45 | ```
46 |
47 | ### الخطافات والمعاملات
48 |
49 | ```js
50 | User.deleted(async (user, { client }) => {
51 | const query = user.related('posts');
52 |
53 | if (client) {
54 | query.transacting(client);
55 | }
56 |
57 | await query.delete();
58 | });
59 |
60 | const trx = await Kawkab.beginTransaction();
61 |
62 | await user.delete({
63 | client: trx
64 | });
65 |
66 | await trx.commit();
67 | ```
68 |
--------------------------------------------------------------------------------
/pages/ar/database/pagination.mdx:
--------------------------------------------------------------------------------
1 | # تعدد الصفحات
2 |
3 | تمتلك Kawkab دعمًا مدمجًا لتعدد الصفحات. يمكنك ترقيم نتائج الاستعلام عن طريق ربط طريقة `paginate`.
4 |
5 | تقبل طريقة `paginate` رقم الصفحة كمعامل أول وعدد الصفوف المطلوب جلبها كمعامل ثانٍ. داخليًا، نقوم بتنفيذ استعلام إضافي لحساب العدد الإجمالي للصفوف.
6 |
7 | ### الاستخدام الأساسي
8 |
9 | ```js
10 | const users = await db.table('users')
11 | .where('vote', '>', 1)
12 | .paginate(2, 15); // instanceof Paginator
13 |
14 | const users = await User.query()
15 | .where('vote', '>', 1)
16 | .paginate(1, 15); // instanceof Paginator
17 |
18 | const users = await db.table('users')
19 | .where('vote', '>', 1)
20 | .forPage(2, 15)
21 | .get(); // instanceof Array
22 |
23 | const users = await User.query()
24 | .where('vote', '>', 1)
25 | .forPage(1, 15)
26 | .get(); // instanceof Collection
27 |
28 | users.map(user => {
29 | //
30 | });
31 | ```
32 |
33 | إذا لم يتم تحديده، فإن عدد الصفوف لكل صفحة يكون افتراضيًا 15. إذا كنت تستخدم النماذج، يمكنك أيضًا تعيين السمة `perPage` كعدد الصفحات الافتراضي لكل نموذج.
34 |
35 | ```js
36 | class Post extends Model {}
37 | class User extends Model {
38 | perPage = 20;
39 | }
40 |
41 | const posts = await Post.query().paginate();
42 | console.log(posts.perPage()); // 15
43 |
44 | const users = await User.query().paginate();
45 | console.log(users.perPage()); // 20
46 | ```
47 |
48 | تعيد طريقة `paginate` مثيلًا من `Paginator`. يحتوي على البيانات الوصفية للترقيم، إلى جانب الصفوف التي تم جلبها.
49 |
50 | يوفر كل مثيل من `Paginator` معلومات إضافية عن الترقيم عبر الطرق التالية:
51 |
52 | | الطريقة | الوصف |
53 | | -------------------------- | --------------------------------------------------------------- |
54 | | `paginator.count()` | الحصول على عدد العناصر للصفحة الحالية. |
55 | | `paginator.currentPage()` | الحصول على رقم الصفحة الحالية. |
56 | | `paginator.hasMorePages()` | تحديد ما إذا كان هناك المزيد من العناصر في مخزن البيانات. |
57 | | `paginator.items()` | الحصول على العناصر للصفحة الحالية. |
58 | | `paginator.lastPage()` | الحصول على رقم الصفحة الأخيرة المتاحة. |
59 | | `paginator.perPage()` | عدد العناصر التي يجب عرضها لكل صفحة. |
60 | | `paginator.total()` | تحديد العدد الإجمالي للعناصر المطابقة في مخزن البيانات. |
61 |
62 | ### التحويلات إلى كائن/JSON
63 |
64 | يمكنك أيضًا تسلسل نتائج المرقم إلى كائن/JSON عن طريق استدعاء طريقة `toData` أو `toJson`. يعيد أسماء المفاتيح في صيغة snake\_case بشكل افتراضي. ومع ذلك، يمكنك تمرير استراتيجية تسمية لتجاوز الاتفاقية الافتراضية.
65 |
66 | ```JSON
67 | {
68 | "total": 45,
69 | "per_page": 15,
70 | "current_page": 1,
71 | "last_page": 3,
72 | "count": 15,
73 | "data": [
74 | {
75 | // Record...
76 | },
77 | {
78 | // Record...
79 | }
80 | ],
81 | }
82 | ```
83 |
84 | سيقوم المرقم بتحويله إلى JSON عند تحويله إلى سلسلة، بحيث يمكن استخدامه مباشرة في مسار التطبيق أو وحدة التحكم. سيقوم تطبيق express/Koa الخاص بك بتسلسل JSON تلقائيًا:
85 |
86 | ```js
87 | const users = await User.query().paginate(req.query.page || 1);
88 |
89 | return res.ok({
90 | "status": true,
91 | "users": users
92 | });
93 |
94 | ```
95 |
--------------------------------------------------------------------------------
/pages/ar/database/transactions.mdx:
--------------------------------------------------------------------------------
1 | # التعامل مع المعاملات (Transactions)
2 |
3 | يمكنك استخدام الطريقة `transaction` المتوفرة في اتصال Sutando لتنفيذ مجموعة من العمليات داخل معاملة قاعدة بيانات. إذا حدث استثناء داخل الإغلاق (closure) الخاص بالمعاملة، فسيتم تلقائيًا التراجع عن المعاملة (rollback) وإعادة طرح الاستثناء. أما إذا تم تنفيذ الإغلاق بنجاح، فستتم الموافقة على المعاملة تلقائيًا. لا داعي للقلق بشأن التراجع يدويًا أو الموافقة عند استخدام طريقة `transaction`:
4 |
5 | ```js
6 | import { db } from "kawkab";
7 |
8 | await db.transaction(async (trx) => {
9 | await User.query().transacting(trx).create(/* ... */);
10 |
11 | await db.table('users').transacting(trx).insert(/* ... */);
12 |
13 | const user = new User;
14 | user.name = 'Sally';
15 |
16 | await user.save({
17 | client: trx,
18 | });
19 | });
20 | ```
21 |
22 | #### استخدام المعاملات يدويًا
23 |
24 | إذا كنت ترغب في بدء معاملة يدويًا والحصول على تحكم كامل بالتراجع والموافقة، يمكنك استخدام طريقة `beginTransaction` المتوفرة من خلال `sutando`:
25 |
26 | ```js
27 | import { db } from "kawkab";
28 |
29 | const trx = await db.beginTransaction();
30 | ```
31 |
32 | يمكنك التراجع عن المعاملة باستخدام طريقة `rollback`:
33 |
34 | ```js
35 | await trx.rollback();
36 | ```
37 |
38 | وأخيرًا، يمكنك الموافقة على المعاملة باستخدام طريقة `commit`:
39 |
40 | ```js
41 | await trx.commit();
42 | ```
43 |
44 | فيما يلي مثال كامل:
45 |
46 | ```js
47 | import { db } from "kawkab";
48 |
49 | const trx = await db.beginTransaction();
50 |
51 | try {
52 | const user = new User;
53 | user.name = 'Sally';
54 |
55 | await user.save({
56 | client: trx,
57 | });
58 |
59 | await trx.commit();
60 | } catch (e) {
61 | await trx.rollback();
62 |
63 | console.log(e.stack);
64 | }
65 | ```
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | localization: {
3 | title: "الترجمة",
4 | },
5 | dto: {
6 | title: "كائن نقل البيانات",
7 | },
8 | enums: {
9 | title: "التعدادات",
10 | },
11 | actions: {
12 | title: "الإجراءات",
13 | },
14 | collections: {
15 | title: "المجموعات",
16 | },
17 | caching: {
18 | title: "التخزين المؤقت",
19 | },
20 | http: {
21 | title: "طلبات HTTP",
22 | },
23 | time: {
24 | title: "الوقت",
25 | },
26 | files: {
27 | title: "الملفات",
28 | },
29 | folders: {
30 | title: "المجلدات",
31 | },
32 | strategies: {
33 | title: "الاستراتيجيات",
34 | },
35 | settings: {
36 | title: "الإعدادات",
37 | },
38 | strings: {
39 | title: "النصوص",
40 | },
41 | numbers: {
42 | title: "الأرقام",
43 | },
44 | data: {
45 | title: "البيانات",
46 | },
47 | logger: {
48 | title: "المسجل",
49 | },
50 | notifications: {
51 | title: "الاشعارات",
52 | },
53 | commands: {
54 | title: "الأوامر",
55 | },
56 | faker: {
57 | title: "البيانات الوهمية",
58 | },
59 | factories: {
60 | title: "المصانع",
61 | },
62 | test: {
63 | title: "الإختبارات",
64 | },
65 | 'test-driven-development': {
66 | title: 'التطوير الموجه بالاختبارات',
67 | },
68 | queue: {
69 | title: "الطوابير",
70 | },
71 | jobs: {
72 | title: "المهام",
73 | },
74 | 'cron-jobs': {
75 | title: "وظائف Cron",
76 | },
77 | "api-documentation": {
78 | title: "توثيق API",
79 | },
80 | };
81 |
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/actions.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: الإجراءات (Actions) باستخدام Kawkab
3 | description: دليل شامل لإنشاء واستخدام الإجراءات في تطبيقك باستخدام الأمر `npm run kawkab action:make`.
4 | ---
5 |
6 | # إنشاء الإجراءات (Actions) باستخدام Kawkab
7 |
8 | الإجراءات (Actions) هي فئات تمثل الأنشطة أو العمليات التي يمكن أن يتم تنفيذها في تطبيقك، مثل تحديث كلمة المرور أو انشاء ارقام عشوائية او غيرها. باستخدام **Kawkab**، يمكنك إنشاء إجراءات بسهولة وتنظيم الأكواد المتعلقة بها بطريقة مرنة لتنفيذ مهمة واحدة محددة.
9 |
10 | ## إنشاء Action جديد باستخدام Kawkab
11 |
12 | لإنشاء **Action** جديد باستخدام **Kawkab**، قم بتشغيل الأمر التالي في سطر الأوامر:
13 |
14 | ```bash
15 | npm run kawkab action:make [module]
16 | ```
17 |
18 | ### **تفاصيل المعلمات:**
19 |
20 | - **``**: اسم الـ Action الذي ترغب في إنشائه (على سبيل المثال `UpdateUserPassword`).
21 | - **`[module]`**: اسم الموديول الذي يحتوي على الـ Action (اختياري، الافتراضي هو `main`).
22 |
23 | ### مثال على كيفية تنفيذ الأمر:
24 |
25 | ```bash
26 | npm run kawkab action:make UpdateUserPassword
27 | ```
28 |
29 | بعد تنفيذ الأمر، سيتم إنشاء **Action** باسم `UpdateUserPassword` في الموديول `main`.
30 |
31 | ### ماذا يحدث بعد تشغيل الأمر؟
32 |
33 | - سيتم إنشاء ملف الـ **Action** باسم `'UpdateUserPassword'` بنجاح.
34 | - يمكنك الآن استخدام هذا الـ **Action** في تطبيقك عن طريق استيراده واستخدامه كما في المثال التالي.
35 |
36 | ## كيفية استخدام Action في التطبيق
37 |
38 | بمجرد إنشاء الـ **Action**، يمكنك استيراده واستخدامه في أي جزء من التطبيق.
39 |
40 | ### استيراد الـ Action:
41 |
42 | لاستيراد الـ **Action** الذي تم إنشاؤه، استخدم الكود التالي في ملفك:
43 |
44 | ```javascript
45 | import { UpdateUserPasswordAction } from "../actions/UpdateUserPassword";
46 | ```
47 |
48 | ### محتوى ملف الـ Action:
49 |
50 | سيحتوي ملف الـ **Action** `UpdateUserPassword` على الكود التالي:
51 |
52 | ```javascript
53 | import { BaseAction } from "kawkab";
54 |
55 | export class UpdateUserPasswordAction extends BaseAction {
56 | handle() {
57 | // إضافة الكود الخاص بالتعامل مع تغيير كلمة المرور هنا
58 | }
59 | }
60 | ```
61 |
62 | ### استخدام الـ Action في التطبيق:
63 |
64 | يمكنك الآن استخدام الـ **Action** من خلال إنشاء كائن جديد من الفئة `UpdateUserPasswordAction` كما يلي:
65 |
66 | ```javascript
67 | const action = new UpdateUserPasswordAction();
68 | action.handle(); // سيتم تنفيذ الكود داخل دالة handle
69 | ```
70 |
71 | #### إرسال البيانات إلى الـ Action:
72 |
73 | يمكنك تمرير البيانات التي تحتاج إليها عند إنشاء كائن الـ **Action**:
74 |
75 | ```javascript
76 | const action = new UpdateUserPasswordAction({ id: 1, name: 'Hassan' });
77 | console.log(action.data); // ستطبع { id: 1, name: 'Hassan' }
78 | ```
79 |
80 | #### الوصول إلى البيانات داخل الـ Action:
81 |
82 | داخل الـ **Action**، يمكنك الوصول إلى البيانات الممررة باستخدام `this.data`:
83 |
84 | ```javascript
85 | export class UpdateUserPasswordAction extends BaseAction {
86 | handle() {
87 | console.log(this.data); // ستطبع البيانات الممررة مثل { id: 1, name: 'Hassan' }
88 | }
89 | }
90 | ```
91 |
92 | ## ملاحظات إضافية
93 |
94 | - **إجراءات متعددة:** يمكنك إنشاء العديد من الإجراءات في تطبيقك باستخدام نفس الأسلوب، حيث يمكنك إنشاء فئات `Action` جديدة لأي عملية تحتاج إليها.
95 | - **توسيع الوظائف:** داخل كل `Action`، يمكنك إضافة منطق الأعمال الخاص بك مثل استعلامات قاعدة البيانات أو التعامل مع البيانات التي تم تمريرها.
96 | - **مرونة في استخدام البيانات:** يمكن تمرير البيانات عند إنشاء الـ **Action** للوصول إليها بسهولة في داخل الـ **Action** باستخدام `this.data`.
97 |
98 | ## الخاتمة
99 |
100 | تعتبر **الإجراءات (Actions)** في Kawkab وسيلة قوية لتنظيم العمليات التي يحتاج تطبيقك إلى تنفيذها. مع **Kawkab**، يمكنك إنشاء واستخدام الإجراءات بسهولة لتنفيذ وظائف مثل تحديث البيانات، إرسال الإشعارات، وأكثر من ذلك بكثير. استفد من المرونة التي يوفرها Kawkab لتنظيم تطبيقك وتحسين كفاءته!
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/commands.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: نظام الأوامر في Kawkab
3 | description: دليل شامل لاستخدام وإنشاء الأوامر في إطار عمل كوكب Kawkab.
4 | ---
5 |
6 | # نظام الأوامر في Kawkab
7 |
8 | نظام **الأوامر** في إطار عمل **Kawkab** يوفر واجهة سطر أوامر قوية ومرنة لإدارة وتنفيذ المهام المختلفة في تطبيقك. يمكنك استخدام الأوامر المدمجة أو إنشاء أوامر مخصصة خاصة بك.
9 |
10 | ## استعراض الأوامر المتاحة
11 |
12 | للحصول على قائمة بجميع الأوامر المتاحة، قم بتنفيذ:
13 |
14 | ```bash
15 | npm run kawkab
16 | ```
17 |
18 | هذا الأمر سيعرض قائمة بجميع الأوامر المتاحة مع وصف مختصر لكل أمر.
19 |
20 | ## إنشاء أمر جديد
21 |
22 | ### الصيغة الأساسية
23 |
24 | ```bash
25 | npm run kawkab command:make [module]
26 | ```
27 |
28 | ### تفاصيل المعلمات:
29 |
30 | - **``**: اسم الأمر الذي ترغب في إنشائه.
31 | - **`[module]`**: اسم الموديول الذي سيحتوي على الأمر (اختياري، الافتراضي هو `main`).
32 |
33 | ### مثال:
34 |
35 | ```bash
36 | npm run kawkab command:make hello
37 | ```
38 |
39 | هذا الأمر سينشئ ملف أمر جديد في المسار المناسب مع الهيكل الأساسي التالي:
40 |
41 | ```typescript
42 | import { Command } from "kawkab";
43 |
44 | export default function(program: Command): void {
45 | program
46 | // صيغة الأمر: '' إلزامي، '[variable_name]' اختياري
47 | .command("hello [module]")
48 | // وصف الأمر الذي سيظهر في مساعدة CLI
49 | .description("وصف الأمر الخاص بك")
50 | // الإجراء الذي سيتم تنفيذه عند تشغيل الأمر
51 | .action(async (name: string, module: string = "main") => {
52 | // قم بكتابة منطق الأمر هنا
53 | console.log(`Hello ${name}`);
54 | });
55 | }
56 | ```
57 |
58 | ## هيكل الأمر
59 |
60 | ### المكونات الأساسية
61 |
62 | 1. **`command()`**: تحديد اسم وصيغة الأمر
63 | - المتغيرات الإلزامية تُكتب بين `<>`
64 | - المتغيرات الاختيارية تُكتب بين `[]`
65 |
66 | 2. **`description()`**: وصف مختصر للأمر يظهر في قائمة المساعدة
67 |
68 | 3. **`action()`**: دالة تحتوي على منطق تنفيذ الأمر
69 | - تستقبل المتغيرات المحددة في صيغة الأمر
70 | - يمكن أن تكون غير متزامنة (`async`)
71 |
72 | ### إضافة خيارات
73 |
74 | يمكنك إضافة خيارات لأمرك باستخدام `option()`:
75 |
76 | ```typescript
77 | program
78 | .command("hello ")
79 | .option("-c, --capitalize", "تحويل الاسم إلى أحرف كبيرة")
80 | .action(async (name: string, options) => {
81 | const output = options.capitalize ? name.toUpperCase() : name;
82 | console.log(`Hello ${output}`);
83 | });
84 | ```
85 |
86 | ## أفضل الممارسات
87 |
88 | 1. **أسماء واضحة**: استخدم أسماء وصفية وواضحة لأوامرك.
89 | 2. **توثيق جيد**: اكتب وصفاً واضحاً ومفصلاً لكل أمر وخياراته.
90 | 3. **التحقق من المدخلات**: تحقق دائماً من صحة المدخلات قبل تنفيذ الأمر.
91 | 4. **رسائل واضحة**: اعرض رسائل واضحة للمستخدم عن نتيجة تنفيذ الأمر.
92 | 5. **معالجة الأخطاء**: قم بتنفيذ معالجة مناسبة للأخطاء المحتملة.
93 |
94 | ## الخاتمة
95 |
96 | نظام الأوامر في Kawkab يوفر طريقة سهلة ومرنة لإضافة وظائف جديدة إلى تطبيقك عبر واجهة سطر الأوامر. مع دعم المتغيرات الإلزامية والاختيارية والخيارات المخصصة، يمكنك إنشاء أوامر قوية ومفيدة لتطبيقك.
97 |
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/data.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: إنشاء ملفات البيانات باستخدام Kawkab
3 | ---
4 |
5 | # ملفات البيانات باستخدام Kawkab
6 |
7 | تُستخدم ملفات البيانات في **Kawkab** لتنظيم وتخزين البيانات الثابتة أو البيانات المعتمدة التي يتم استخدامها في تطبيقك. يمكن أن تكون هذه البيانات عبارة عن قوائم، إعدادات، أو أي معلومات ثابتة أخرى تود استخدامها في مشروعك بطريقة منظمة.
8 |
9 | ## إنشاء ملفات البيانات باستخدام Kawkab
10 |
11 | في هذا الدليل، سنوضح كيفية إنشاء ملفات بيانات جديدة باستخدام إطار العمل **Kawkab** ودمجها في تطبيقك.
12 |
13 | ## الخطوة 1: إنشاء ملف بيانات جديد
14 |
15 | لإنشاء ملف بيانات جديد باستخدام **Kawkab**، قم بتشغيل الأمر التالي في سطر الأوامر:
16 |
17 | ```bash
18 | npm run kawkab data:make [module]
19 | ```
20 |
21 | ### **تفاصيل المعلمات:**
22 |
23 | - **``**: اسم ملف البيانات الذي ترغب في إنشائه (على سبيل المثال `cats`).
24 | - **`[module]`**: اسم الموديول الذي يحتوي على البيانات (اختياري، الافتراضي هو `main`).
25 |
26 | ### مثال على كيفية تنفيذ الأمر:
27 |
28 | ```bash
29 | npm run kawkab data:make cats
30 | ```
31 |
32 | هذا الأمر سينشئ ملف بيانات باسم `cats` داخل الموديول `main`.
33 |
34 | ### ماذا يحدث بعد تشغيل الأمر؟
35 |
36 | - سيتم إنشاء ملف بيانات باسم `'cats'` في الموديول المحدد.
37 | - سيحتوي هذا الملف على البيانات التي يمكن استخدامها في التطبيق. على سبيل المثال، في هذا الدليل سيتم إنشاء ملف يحتوي على قائمة بأنواع القطط المشهورة.
38 |
39 | ## الخطوة 2: كيفية استخدام البيانات في التطبيق
40 |
41 | بمجرد إنشاء ملف البيانات، يمكنك استيراده واستخدامه داخل ملفات المشروع الخاصة بك.
42 |
43 | ### استيراد البيانات:
44 |
45 | لاستيراد البيانات التي تم إنشاؤها، استخدم الكود التالي في ملفك:
46 |
47 | ```javascript
48 | import catsData from '../data/cats';
49 | ```
50 |
51 | ### محتوى ملف البيانات:
52 |
53 | سيحتوي ملف البيانات `cats` على البيانات التالية (أنواع القطط):
54 |
55 | ```javascript
56 | export default {
57 | data: [
58 | "Persian", // قطط فارسية
59 | "Maine Coon", // قطط مين كون
60 | "Bengal", // قطط بنغالية
61 | "Siamese", // قطط سيامية
62 | "Ragdoll", // قطط راغدول
63 | "British Shorthair", // قطط شورتير البريطاني
64 | "Sphynx", // قطط سفينكس
65 | "Abyssinian", // قطط أبيسينيان
66 | "Scottish Fold", // قطط سكوتش فولد
67 | "Birman" // قطط بيرمان
68 | ]
69 | }
70 | ```
71 |
72 | ### استخدام البيانات في التطبيق:
73 |
74 | الآن، يمكنك الوصول إلى البيانات واستخدامها بسهولة في أي جزء من التطبيق:
75 |
76 | ```javascript
77 | const data = catsData.data;
78 | console.log(data); // سيطبع لك قائمة بأنواع القطط
79 | ```
80 |
81 | ## ملاحظات إضافية
82 |
83 | - تأكد من أن المسار الذي تستخدمه لاستيراد البيانات صحيح بناءً على هيكل المجلدات في مشروعك.
84 | - يمكنك استخدام نفس الأسلوب لإنشاء ملفات بيانات أخرى بتغيير اسم الملف الذي تم إنشاؤه (مثل `dogs` بدلاً من `cats`).
85 |
86 | - إذا كنت تستخدم أكثر من موديول، يمكنك تحديد الموديول الذي يحتوي على البيانات باستخدام المعامل `[module]`:
87 |
88 | ```bash
89 | npm run kawkab data:make cats customModuleName
90 | ```
91 |
92 | ## الخاتمة
93 |
94 | إنشاء ملفات البيانات باستخدام Kawkab يساهم في تنظيم وتبسيط إدارة البيانات الثابتة في تطبيقك. بفضل Kawkab، يمكنك إنشاء هذه الملفات بسهولة ودمجها في تطبيقك بسرعة. استمتع باستخدام **Kawkab** لتطوير تطبيقاتك بشكل أكثر كفاءة ومرونة!
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/dto.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: إنشاء كائن نقل البيانات (DTO) باستخدام Kawkab
3 | description: دليل شامل لإنشاء واستخدام كائنات نقل البيانات (DTO) في تطبيقك باستخدام Kawkab.
4 | ---
5 |
6 | # كائن نقل البيانات (DTO) باستخدام Kawkab
7 |
8 | **كائن نقل البيانات (Data Transfer Object - DTO)** هو كائن يستخدم لنقل البيانات بين الطبقات المختلفة في تطبيقك بطريقة منظمة ومرنة. مع **Kawkab**، يمكنك إنشاء كائنات DTO بسهولة واستخدامها لإدارة البيانات الواردة من الطلبات أو البيانات الممررة بين الأجزاء المختلفة من التطبيق.
9 |
10 | ---
11 |
12 | ## إنشاء DTO جديد باستخدام Kawkab
13 |
14 | لإنشاء **DTO** جديد، قم بتنفيذ الأمر التالي:
15 |
16 | ```bash
17 | npm run kawkab dto:make [module]
18 | ```
19 |
20 | ### **تفاصيل المعاملات:**
21 |
22 | - **``**: اسم الـ DTO الذي تريد إنشاؤه (مثل `User`).
23 | - **`[module]`**: اسم الموديول الذي يحتوي على الـ DTO (اختياري، الافتراضي هو `main`).
24 |
25 | ### **مثال عملي:**
26 |
27 | ```bash
28 | npm run kawkab dto:make user
29 | ```
30 |
31 | ### **نتيجة التنفيذ:**
32 |
33 | - سيتم إنشاء كائن DTO باسم `UserDTO` في الموديول `main`.
34 | - يمكنك الآن استخدام هذا الـ DTO بسهولة في تطبيقك.
35 |
36 | ---
37 |
38 | ## كيفية استخدام DTO في التطبيق
39 |
40 | بمجرد إنشاء كائن DTO، يمكنك استيراده واستخدامه في ملفات المشروع.
41 |
42 | ### استيراد DTO:
43 |
44 | للاستفادة من الـ DTO، استخدم الاستيراد التالي:
45 |
46 | ```javascript
47 | import { UserDTO } from "../dto/user";
48 | ```
49 |
50 | ### إنشاء كائن DTO:
51 |
52 | يمكنك إنشاء كائن DTO جديد بثلاث طرق:
53 |
54 | #### 1. **إنشاء كائن بدون تمرير بيانات:**
55 |
56 | عند عدم تمرير بيانات، سيقوم كائن الـ DTO تلقائيًا بجلب البيانات من الطلب (Request):
57 |
58 | ```javascript
59 | const dto = new UserDTO();
60 | console.log(dto.data); // يحتوي على البيانات من الطلب الحالي
61 | ```
62 |
63 | #### 2. **تمرير بيانات مباشرة عند الإنشاء:**
64 |
65 | يمكنك تمرير البيانات يدويًا عند إنشاء الكائن:
66 |
67 | ```javascript
68 | const dto = new UserDTO({
69 | email: "hassan@example.com",
70 | });
71 | console.log(dto.data); // يحتوي على { email: "hassan@example.com" }
72 | ```
73 |
74 | ---
75 |
76 | ## محتوى ملف DTO:
77 |
78 | سيحتوي ملف `UserDTO` الذي تم إنشاؤه على الكود التالي:
79 |
80 | ```javascript
81 | import { BaseDTO, rule as r, req } from "kawkab";
82 |
83 | export interface Item {
84 | [key: string]: any;
85 | }
86 |
87 | export class UserDTO extends BaseDTO {
88 | constructor(data: Item = req.inputs()) {
89 | super();
90 | this.dto(this, data);
91 | }
92 |
93 | static inject(data: Item = req.inputs()) {
94 | return { ...new this(data) };
95 | }
96 |
97 | data(i: Item): object {
98 | return {
99 | email: i?.email,
100 | };
101 | }
102 |
103 | rules() {
104 | return {
105 | email: r.string().email(),
106 | };
107 | }
108 | }
109 | ```
110 |
111 | ---
112 |
113 | ## ملاحظات إضافية
114 |
115 | 1. **التحقق من صحة البيانات:**
116 | - يمكن تعريف قواعد التحقق باستخدام الدالة `rules()`. في المثال أعلاه، تم تعريف قاعدة للتحقق من صحة البريد الإلكتروني.
117 |
118 | 2. **جلب البيانات الافتراضية:**
119 | - يتم جلب بيانات الطلب افتراضيًا باستخدام `req.inputs()` إذا لم يتم تمرير بيانات عند إنشاء الكائن.
120 |
121 | 3. **تنظيم البيانات:**
122 | - يمكنك تحديد شكل البيانات النهائية عبر الدالة `data()`.
123 |
124 | ---
125 |
126 | ## الخاتمة
127 |
128 | يوفر Kawkab طريقة مرنة لإنشاء كائنات نقل البيانات (DTO) لتنظيم البيانات والتحقق من صحتها بسهولة. باستخدام هذا الأسلوب، يمكنك تحسين كود التطبيق وفصل منطق البيانات عن منطق الأعمال. استفد من هذه الميزة لتطوير تطبيقات أكثر استقرارًا وتنظيمًا.
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/enums.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: إنشاء Enums باستخدام Kawkab
3 | description: دليل شامل لإنشاء واستخدام Enums في تطبيقك باستخدام الأمر `npm run kawkab enum:make`.
4 | ---
5 |
6 | # إنشاء التعدادات Enums باستخدام Kawkab
7 |
8 | **Enums** هي طريقة رائعة لتنظيم القيم الثابتة والمحددة مسبقًا في تطبيقك بطريقة مرتبة وقابلة للتوسع. في هذا الدليل، سنتعرف على كيفية إنشاء واستخدام **Enums** باستخدام إطار العمل **Kawkab**.
9 |
10 | ## إنشاء Enum جديد باستخدام Kawkab
11 |
12 | لإنشاء **Enum** جديد باستخدام **Kawkab**، قم بتشغيل الأمر التالي في سطر الأوامر:
13 |
14 | ```bash
15 | npm run kawkab enum:make [module]
16 | ```
17 |
18 | ### **تفاصيل المعلمات:**
19 |
20 | - **``**: اسم الـ Enum الذي ترغب في إنشائه (على سبيل المثال `UserType`).
21 | - **`[module]`**: اسم الموديول الذي يحتوي على الـ Enum (اختياري، الافتراضي هو `main`).
22 |
23 | ### مثال على كيفية تنفيذ الأمر:
24 |
25 | ```bash
26 | npm run kawkab enum:make UserType
27 | ```
28 |
29 | بعد تنفيذ الأمر، سيتم إنشاء Enum باسم `UserType` في الموديول `main`.
30 |
31 | ### ماذا يحدث بعد تشغيل الأمر؟
32 |
33 | - سيتم إنشاء ملف Enum باسم `'UserType'` بنجاح.
34 | - يمكنك الآن استخدام الـ Enum في تطبيقك عن طريق استيراده واستخدامه كما في المثال التالي.
35 |
36 | ## كيفية استخدام Enum في التطبيق
37 |
38 | بمجرد إنشاء الـ Enum، يمكنك استيراده واستخدامه في أي جزء من التطبيق.
39 |
40 | ### استيراد الـ Enum:
41 |
42 | لاستيراد الـ Enum الذي تم إنشاؤه، استخدم الكود التالي في ملفك:
43 |
44 | ```javascript
45 | import { UserType, UserTypeEnum } from "../enums/UserType";
46 | ```
47 |
48 | ### محتوى ملف الـ Enum:
49 |
50 | سيحتوي ملف الـ Enum `UserType` على القيم التالية:
51 |
52 | ```javascript
53 | import { BaseEnum as Enum } from "kawkab";
54 |
55 | export enum UserTypeEnum {
56 | Administrator = 0, // مشرف
57 | Moderator = 1, // مشرف فرعي
58 | Subscriber = 2, // مشترك
59 | SuperAdministrator = 3, // مشرف رئيسي
60 | // يمكنك إضافة القيم الأخرى هنا
61 | }
62 |
63 | Enum.set(UserTypeEnum);
64 |
65 | export class UserType extends Enum {}
66 | ```
67 |
68 | ### استخدام الـ Enum في التطبيق:
69 |
70 | يمكنك استخدام الـ Enum بعدة طرق كما في المثال التالي:
71 |
72 | #### الطريقة الأولى: الوصول إلى القيم باستخدام الـ Enum
73 |
74 | ```javascript
75 | console.log(UserTypeEnum.Administrator); // سيطبع 0
76 | console.log(UserTypeEnum.Moderator); // سيطبع 1
77 | ```
78 |
79 | #### الطريقة الثانية: استخدام طريقة `get` للوصول إلى القيم
80 |
81 | ```javascript
82 | console.log(UserType.get('Administrator')); // سيطبع 0
83 | console.log(UserType.get('Subscriber')); // سيطبع 2
84 | ```
85 |
86 | ## ملاحظات إضافية
87 |
88 | - **استخدام Enum مع فئات أخرى:** يمكنك استخدام الـ Enum في أي مكان في التطبيق حيث تحتاج إلى تمثيل القيم الثابتة. يمكن أن تكون هذه القيم تمثل أنواع المستخدمين، أو الحالة الخاصة بشيء معين.
89 | - **مرونة:** يمكن إضافة المزيد من القيم بسهولة داخل الـ Enum في أي وقت.
90 | - **إعادة التسمية:** إذا كنت بحاجة إلى إعادة تسمية القيم في الـ Enum، يمكنك تعديلها بشكل مباشر داخل الملف.
91 |
92 | ## الخاتمة
93 |
94 | إن استخدام **Enums** في Kawkab يساعد على تنظيم القيم الثابتة في تطبيقك بطريقة أكثر وضوحًا وقوة. بفضل **Kawkab**، يمكنك إنشاء واستخدام Enums بطريقة مرنة ومبسطة داخل مشروعك. استمتع بتطوير تطبيقاتك بشكل أكثر كفاءة وتنظيمًا!
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/factories.mdx:
--------------------------------------------------------------------------------
1 | # المصانع في Kawkab
2 |
3 | ## نظرة عامة
4 | المصانع في Kawkab هي طريقة سهلة وفعالة لإنشاء بيانات وهمية لأغراض الاختبار والتطوير. تستخدم المصانع مكتبة Faker لتوليد بيانات واقعية.
5 |
6 | ## الاستخدام الأساسي
7 |
8 | ### إنشاء مصنع جديد
9 |
10 | لإنشاء **Factory** جديد، قم بتنفيذ الأمر التالي:
11 |
12 | ```bash
13 | npm run kawkab factory:make [module]
14 | ```
15 |
16 | ### **تفاصيل المعاملات:**
17 |
18 | - **``**: اسم الـ Factory الذي تريد إنشاؤه (مثل `User`).
19 | - **`[module]`**: اسم الموديول الذي يحتوي على الـ Factory (اختياري، الافتراضي هو `main`).
20 |
21 | ### **مثال عملي:**
22 |
23 | ```bash
24 | npm run kawkab factory:make user
25 | ```
26 |
27 | ```typescript
28 | import { BaseFactory, faker } from 'kawkab';
29 | import { User } from "../models/user";
30 |
31 | export class UserFactory extends BaseFactory {
32 | async handle() {
33 | const data = {
34 | username: faker.internet.userName(),
35 | email: faker.internet.email()
36 | };
37 |
38 | await User.query().insert(data);
39 | }
40 | }
41 | ```
42 |
43 | ### استخدام المصنع
44 |
45 | ```typescript
46 | // إنشاء 10 مستخدمين
47 | new UserFactory(10);
48 |
49 | // إنشاء مستخدم واحد
50 | new UserFactory();
51 | ```
52 |
53 | ## المميزات الرئيسية
54 |
55 | 1. **البساطة**: إنشاء البيانات بسطر واحد من الكود
56 | 2. **المرونة**: يمكن تخصيص البيانات المولدة حسب الحاجة
57 | 3. **التلقائية**: يتم إدخال البيانات في قاعدة البيانات تلقائياً
58 | 4. **قابلية التوسع**: يمكن إضافة مصانع جديدة بسهولة
59 |
60 | ## أفضل الممارسات
61 |
62 | 1. **تنظيم المصانع**:
63 | - ضع كل المصانع في مجلد `factories`
64 | - اتبع نمط التسمية `[ModelName]Factory`
65 |
66 | 2. **البيانات**:
67 | - استخدم faker لتوليد بيانات واقعية
68 | - تجنب البيانات الثابتة إلا عند الضرورة
69 | - تأكد من تغطية جميع الحقول المطلوبة
70 |
71 | 3. **العلاقات**:
72 | - قم بإنشاء السجلات المرتبطة أولاً
73 | - استخدم المصانع الأخرى لإنشاء البيانات المرتبطة
74 |
75 | 4. **الاختبارات**:
76 | - استخدم المصانع في ملفات الاختبار
77 | - قم بإنشاء بيانات اختبار متنوعة
78 | - تأكد من تنظيف البيانات بعد الاختبارات
79 |
80 | ## ملاحظات هامة
81 |
82 | 1. المصانع مصممة للاستخدام في بيئة التطوير والاختبار فقط
83 | 2. لا تستخدم المصانع في بيئة الإنتاج
84 | 3. تأكد من استخدام إصدار متوافق من Faker
85 | 4. قم بتنظيف البيانات المولدة بشكل دوري
86 |
87 | ## الخاتمة
88 |
89 | المصانع في Kawkab توفر طريقة سهلة وفعالة لإنشاء بيانات اختبار. يمكنك بسرعة إنشاء بيانات واقعية لتطبيقك.
90 |
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/logger.mdx:
--------------------------------------------------------------------------------
1 | # المسجل Logger في كوكب Kawkab
2 |
3 | ## المقدمة
4 | التسجيل (Logging) جزء أساسي من أي تطبيق، حيث يساعد على تتبع حالة النظام وسلوكه. إطار العمل **كوكب Kawkab** يوفر نظام تسجيل مدمج يتيح لك تسجيل الرسائل بمستويات متعددة مثل: `info`، `warn`، `error`، `verbose`، `debug`، و`silly`.
5 |
6 | ---
7 |
8 | ## استخدام نظام التسجيل
9 |
10 | ### الاستيراد
11 | لبدء استخدام نظام التسجيل في **كوكب Kawkab**، يجب استيراد `log` من مكتبة **kawkab**:
12 |
13 | ```ts
14 | import { log } from "kawkab";
15 | ```
16 |
17 | ---
18 |
19 | ## تسجيل الرسائل
20 |
21 | ### تسجيل رسالة عامة
22 | لتسجيل رسالة بمستوى معين، استخدم الدالة `message` مع تحديد مستوى السجل المطلوب.
23 |
24 | #### مثال:
25 | ```ts
26 | log.message('info', 'هذه رسالة معلوماتية.');
27 | ```
28 |
29 | ---
30 |
31 | ### تسجيل رسالة خطأ
32 | لتسجيل رسالة خطأ، استخدم الطريقة `error`:
33 |
34 | #### مثال:
35 | ```ts
36 | log.error('حدث خطأ في النظام.');
37 | ```
38 |
39 | ---
40 |
41 | ### تسجيل رسالة تحذير
42 | لتسجيل رسالة تحذيرية، استخدم الطريقة `warn`:
43 |
44 | #### مثال:
45 | ```ts
46 | log.warn('هذه رسالة تحذيرية.');
47 | ```
48 |
49 | ---
50 |
51 | ### تسجيل رسالة معلوماتية
52 | لتسجيل رسالة معلوماتية، استخدم الطريقة `info`:
53 |
54 | #### مثال:
55 | ```ts
56 | log.info('هذه رسالة معلوماتية.');
57 | ```
58 |
59 | ---
60 |
61 | ### تسجيل رسالة تفصيلية
62 | لتسجيل رسالة تحتوي على تفاصيل أكثر من المستوى المعلوماتي، استخدم الطريقة `verbose`:
63 |
64 | #### مثال:
65 | ```ts
66 | log.verbose('هذه رسالة تحتوي على تفاصيل إضافية.');
67 | ```
68 |
69 | ---
70 |
71 | ### تسجيل رسالة تصحيحية (Debugging)
72 | لتسجيل رسالة تصحيحية أثناء التطوير، استخدم الطريقة `debug`:
73 |
74 | #### مثال:
75 | ```ts
76 | log.debug('هذه رسالة تصحيحية.');
77 | ```
78 |
79 | ---
80 |
81 | ### تسجيل رسالة تفصيلية جدًا
82 | لتسجيل رسالة بأعلى مستوى من التفاصيل، استخدم الطريقة `silly`:
83 |
84 | #### مثال:
85 | ```ts
86 | log.silly('هذه رسالة شديدة التفصيل.');
87 | ```
88 |
89 | ---
90 |
91 | ## تخزين السجلات
92 |
93 | ### ملف السجلات
94 | يتم تخزين جميع الرسائل المسجلة في ملف باسم `app.log`.
95 | يحتوي هذا الملف على جميع الأحداث المسجلة ويمكن استخدامه لمراجعة السجلات وتحليل أداء النظام.
96 |
97 | #### مثال على محتويات ملف السجل:
98 | ```
99 | [2024-11-28T14:32:00.000Z] [INFO] - تم تشغيل التطبيق بنجاح.
100 | [2024-11-28T14:33:00.000Z] [ERROR] - حدث خطأ في قاعدة البيانات.
101 | ```
102 |
103 | ---
104 |
105 | ## الخاتمة
106 |
107 | يوفر **كوكب Kawkab** نظام تسجيل شامل وسهل الاستخدام، مما يتيح للمطورين تسجيل الرسائل بمستويات متعددة بسهولة.
108 | يمكنك استخدام هذا النظام لتتبع حالة النظام، تحديد المشاكل المحتملة، وتحليل أداء التطبيق.
109 |
110 | ابدأ باستخدام نظام التسجيل اليوم لجعل تطبيقك أكثر استقرارًا واحترافية!
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/notifications.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: نظام الإشعارات في Kawkab
3 | description: دليل شامل لاستخدام نظام الإشعارات في تطبيقك باستخدام إطار عمل كوكب Kawkab.
4 | ---
5 |
6 | # نظام الإشعارات في Kawkab
7 |
8 | نظام **الإشعارات** في إطار عمل **Kawkab** يوفر واجهة برمجية بسيطة وقوية لإرسال وإدارة الإشعارات في تطبيقك. يدعم النظام إرسال الإشعارات عبر قنوات متعددة مثل البريد الإلكتروني، والرسائل النصية، والإشعارات المباشرة في التطبيق.
9 |
10 | ## البدء باستخدام نظام الإشعارات
11 |
12 | ### إنشاء إشعار جديد
13 |
14 | يمكنك إنشاء إشعار جديد باستخدام أمر CLI المدمج في Kawkab:
15 |
16 | ```bash
17 | npm run kawkab notification:make SendWelcomeNotification
18 | ```
19 |
20 | ### **تفاصيل المعلمات:**
21 |
22 | - **``**: اسم الـ Notification الذي ترغب في إنشائه.
23 | - **`[module]`**: اسم الموديول الذي يحتوي على الـ Action (اختياري، الافتراضي هو `main`).
24 |
25 | ---
26 |
27 | مثال:
28 |
29 | ```bash
30 | npm run kawkab notification:make [module]
31 | ```
32 |
33 | هذا الأمر سينشئ ملف إشعار جديد في مجلد `notifications` مع الهيكل الأساسي المطلوب.
34 |
35 | ### هيكل الإشعار الأساسي
36 |
37 | ```typescript
38 | import { BaseNotification, mail } from "kawkab";
39 |
40 | export class SendOtpCodeNotification extends BaseNotification {
41 | static async via() {
42 | await this.email();
43 | }
44 |
45 | static async email() {
46 | await mail.send({
47 | to: this.data.email,
48 | subject: "Hello!",
49 | subject: "مرحباً بك في تطبيقنا",
50 | });
51 | }
52 | }
53 | ```
54 |
55 | ## الميزات الأساسية
56 |
57 | ### تحديد قنوات الإرسال
58 |
59 | يمكنك تحديد قناة أو عدة قنوات لإرسال الإشعار من خلال دالة `via()`:
60 |
61 | ```typescript
62 | static async via() {
63 | await this.email();
64 | }
65 | ```
66 |
67 | ## أفضل الممارسات
68 |
69 | 1. **فصل المنطق**: احرص على فصل منطق الإشعارات عن باقي منطق التطبيق.
70 | 2. **استخدام القوالب**: استخدم قوالب للرسائل المتكررة لتسهيل الصيانة والتحديث.
71 | 3. **التعامل مع الأخطاء**: قم بتنفيذ معالجة مناسبة للأخطاء وتسجيل الأحداث المهمة.
72 | 4. **اختبار الإشعارات**: قم بكتابة اختبارات للتأكد من عمل نظام الإشعارات بشكل صحيح.
73 |
74 | ## الخاتمة
75 |
76 | يوفر نظام الإشعارات في Kawkab حلاً مرناً وقوياً لإدارة وإرسال الإشعارات في تطبيقك. مع دعم القنوات المتعددة والقوالب المخصصة، يمكنك بسهولة تنفيذ أي متطلبات خاصة بالإشعارات في تطبيقك.
77 |
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/queue.mdx:
--------------------------------------------------------------------------------
1 | # نظام الطوابير (Queue)
2 |
3 | نظام الطوابير في إطار Kawkab يوفر طريقة فعالة لمعالجة المهام في الخلفية. يمكن استخدام نوعين من أنظمة الطوابير:
4 |
5 | ## 1. طابور الذاكرة (Memory Queue)
6 | هذا هو النظام الافتراضي عندما يكون `QUEUE_ENABLE_REDIS=false`. يتم تخزين المهام في ذاكرة التطبيق مباشرة.
7 |
8 | ### المميزات:
9 | - سهل الإعداد - لا يحتاج إلى خدمات خارجية
10 | - مناسب للتطوير المحلي والتطبيقات الصغيرة
11 | - يتم فقدان المهام عند إعادة تشغيل التطبيق
12 |
13 | ## 2. طابور Redis
14 | يتم تفعيله عند ضبط `QUEUE_ENABLE_REDIS=true`. يستخدم Redis كنظام تخزين للمهام.
15 |
16 | ### الإعدادات في ملف .env:
17 | ```env
18 | QUEUE_ENABLE_REDIS=true
19 | QUEUE_REDIS_HOST=127.0.0.1
20 | QUEUE_REDIS_PORT=6379
21 | ```
22 |
23 | ### المميزات:
24 | - موثوقية عالية - المهام تبقى محفوظة حتى بعد إعادة تشغيل التطبيق
25 | - قابلية للتوسع - يمكن معالجة عدد كبير من المهام
26 | - مناسب للإنتاج والتطبيقات الكبيرة
27 |
28 | ## ملاحظات مهمة
29 | - تأكد من تشغيل خادم Redis إذا كنت تستخدم طابور Redis
30 | - يمكن تعديل إعدادات الطابور في ملف `configuration.ts`
31 | - يتم معالجة المهام تلقائياً في الخلفية
32 |
--------------------------------------------------------------------------------
/pages/ar/digging-deeper/settings.mdx:
--------------------------------------------------------------------------------
1 | # الإعدادات Settings في كوكب Kawkab
2 |
3 | **الإعدادات Settings** هي طريقة منظمة لتخزين القيم والمفاتيح التي تُستخدم عبر المشروع لتخصيص السلوكيات أو تفعيل وتعطيل ميزات معينة. يوفر كوكب Kawkab أداة قوية لإنشاء ملفات إعدادات بسهولة وسرعة.
4 |
5 | ---
6 |
7 | ## إنشاء ملف إعدادات
8 |
9 | لإنشاء ملف إعدادات جديد في كوكب Kawkab، يمكنك استخدام الأمر التالي:
10 |
11 | ```bash
12 | setting:make [module]
13 | ```
14 |
15 | ### الأجزاء:
16 | - **``**: اسم ملف الإعدادات (على سبيل المثال: `auth`).
17 | - **`[module]`**: اسم الوحدة (Module) التي سيتم إنشاء الإعدادات داخلها. إذا لم يتم تحديد وحدة، يتم إنشاء الملف في الوحدة الافتراضية `main`.
18 |
19 | ---
20 |
21 | ## مثال عملي
22 |
23 | لنفترض أنك تريد إنشاء ملف إعدادات باسم `auth`، قم بتنفيذ الأمر التالي:
24 |
25 | ```bash
26 | npm run kawkab setting:make auth
27 | ```
28 |
29 | ### النتيجة:
30 | ستظهر الرسالة التالية بعد التنفيذ:
31 |
32 | ```
33 | 🆗 Setting file 'auth' created successfully in module 'main'.
34 |
35 | 1️⃣ Your setting file is ready! You can now import it like this:
36 | 👉 import { setting } from '../settings/auth'
37 |
38 | 2️⃣ Use the setting like so:
39 | 👉 const enable:boolean = setting.enable
40 | ```
41 |
42 | ### ماذا حدث؟
43 | 1. تم إنشاء ملف إعدادات جديد باسم `auth` داخل المجلد الافتراضي للوحدة `main`.
44 | 2. يحتوي الملف على إعدادات جاهزة للاستخدام.
45 | 3. يمكنك الآن استيراد الإعدادات واستخدامها في مشروعك.
46 |
47 | ---
48 |
49 | ## استخدام الإعدادات
50 |
51 | بعد إنشاء ملف الإعدادات، يمكنك استيراده واستخدامه بسهولة في أي مكان في مشروعك.
52 |
53 | ### مثال:
54 | #### ملف الإعدادات: `auth.ts`
55 | ```ts
56 | export const setting = {
57 | enable: true, // لتفعيل أو تعطيل المصادقة
58 | loginAttempts: 5, // عدد محاولات تسجيل الدخول المسموح بها
59 | timeout: 300, // مدة انتهاء الجلسة بالثواني
60 | };
61 | ```
62 |
63 | #### استخدام الإعدادات:
64 | ```ts
65 | import { setting } from '../settings/auth';
66 |
67 | // قراءة إعداد معين
68 | const isAuthEnabled = setting.enable;
69 | console.log(`Authentication Enabled: ${isAuthEnabled}`);
70 |
71 | // استخدام إعداد آخر
72 | if (setting.enable) {
73 | console.log(`Maximum Login Attempts: ${setting.loginAttempts}`);
74 | console.log(`Session Timeout: ${setting.timeout} seconds`);
75 | }
76 | ```
77 |
78 | ---
79 |
80 | ## تخصيص الوحدة (Module)
81 |
82 | إذا كنت تريد إنشاء ملف إعدادات ضمن وحدة مخصصة بدلاً من الوحدة الافتراضية `main`، يمكنك تحديد اسم الوحدة أثناء التنفيذ.
83 |
84 | ### مثال:
85 | ```bash
86 | npm run kawkab setting:make database app
87 | ```
88 |
89 | ### النتيجة:
90 | - سيتم إنشاء ملف إعدادات باسم `database` داخل وحدة `app`.
91 | - الرسالة الناتجة:
92 | ```
93 | 🆗 Setting file 'database' created successfully in module 'app'.
94 |
95 | 1️⃣ Your setting file is ready! You can now import it like this:
96 | 👉 import { setting } from '../app/settings/database'
97 |
98 | 2️⃣ Use the setting like so:
99 | 👉 const maxConnections:number = setting.maxConnections
100 | ```
101 |
102 | ---
103 |
104 | ## فوائد استخدام الإعدادات
105 |
106 | 1. **تنظيم القيم الأساسية**: فصل الإعدادات عن الكود الأساسي لتسهيل إدارتها.
107 | 2. **قابلية التخصيص**: يمكن تعديل الإعدادات بسهولة لتغيير سلوك التطبيق دون الحاجة إلى تعديل الكود.
108 | 3. **إعادة الاستخدام**: إعدادات موحدة يمكن استخدامها في أكثر من مكان.
109 | 4. **سهولة الصيانة**: تعديلات أقل عند تحديث الإعدادات مقارنة بالتعديلات داخل الكود.
110 |
111 | ---
112 |
113 | ## نصائح عملية
114 |
115 | - **استخدام أسماء وصفية للإعدادات**: تأكد من أن أسماء الإعدادات تعبر عن وظيفتها.
116 | - **تنظيم الإعدادات حسب الوحدة**: إذا كنت تعمل على مشروع كبير، يفضل تقسيم الإعدادات إلى وحدات لتسهيل إدارتها.
117 | - **تحديث الإعدادات بسهولة**: استخدم ملفات الإعدادات لتجنب تكرار القيم أو الحاجة إلى تعديل الكود الأساسي عند تغيير الإعدادات.
118 |
119 | ---
120 |
121 | بهذا، يمكنك إدارة إعدادات مشروعك في **كوكب Kawkab** بسهولة وفعالية باستخدام أداة **Settings**.
--------------------------------------------------------------------------------
/pages/ar/getting-started/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'installation': {
3 | title: 'التثبيت',
4 | },
5 | 'production': {
6 | title: 'النشر',
7 | },
8 | 'directory-structure': {
9 | title: 'هيكل المجلدات',
10 | },
11 | 'architecture': {
12 | title: 'الهيكلية',
13 | },
14 | 'file-based-routing': {
15 | title: 'التوجيه القائم على الملفات',
16 | },
17 | 'modules': {
18 | title: 'الوحدات',
19 | },
20 | 'mvc-architecture': {
21 | title: 'الهيكلية MVC',
22 | },
23 | 'hmvc-architecture': {
24 | title: 'الهيكلية HMVC',
25 | },
26 | 'configuration': {
27 | title: 'التكوينات',
28 | },
29 | 'environment-variables': {
30 | title: 'المتغيرات البيئية',
31 | },
32 | }
33 |
--------------------------------------------------------------------------------
/pages/ar/getting-started/architecture.mdx:
--------------------------------------------------------------------------------
1 | # **بنية كوكب**
2 |
3 | يعتمد إطار **كوكب** على بنية **HMVC** (نموذج-عرض-تحكم هرمي) لتعزيز تنظيم المشروع وقابليته للتوسع.
4 |
5 | ## **نظرة عامة**
6 |
7 | تقسم بنية HMVC المشروع إلى وحدات هرمية متميزة، مما يحسن فصل المهام ويسمح بتنظيم التطبيق بشكل أكثر مرونة. هذه البنية تمكّن من بناء تطبيقات معقدة بطريقة منظمة وقابلة للتوسع.
8 |
9 | ## **الميزات الرئيسية**
10 |
11 | - **الهيكلية الوحدوية**: يتم تنظيم المشروع إلى وحدات منفصلة، كل وحدة تتعامل مع وظيفة معينة داخل التطبيق.
12 | - **الوحدة الرئيسية**: يتضمن كوكب وحدة رئيسية بشكل افتراضي، والتي تعمل كنواة للنظام.
13 | - **قابلية التوسع**: يدعم التصميم الوحدوي التوسع والصيانة بسهولة في التطبيق.
14 |
15 | ## **الفوائد**
16 |
17 | - **تحسين التنظيم**: تقسيم المشروع إلى وحدات واضحة يعزز تنظيم المشروع وإدارته.
18 | - **تعزيز قابلية التوسع**: إضافة أو تحديث الميزات يصبح أسهل وأكثر سلاسة، مما يعزز النمو المستدام للمشروع.
19 | - **فصل المهام**: كل وحدة تركز على جوانب معينة من التطبيق، مما يقلل من التعقيد ويزيد من سهولة الصيانة.
20 |
21 | من خلال اعتماد بنية HMVC، يوفر كوكب إطار عمل قويًا لبناء تطبيقات قابلة للتوسع ومنظمة بشكل جيد، مما يسهل تطوير المشاريع الكبيرة والمعقدة.
--------------------------------------------------------------------------------
/pages/ar/getting-started/directory-structure.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "هيكل الدليل في Kawkab"
3 | ---
4 |
5 | إطار العمل **كوكب** يعتمد على هيكل منظم ومتقدم لدعم التنظيم المرن والفعال لجميع جوانب التطبيق. تم تصميم هذا الهيكل لضمان كفاءة عالية في التطوير وسهولة التوسع على المدى الطويل.
6 |
7 | ## **📂 app**
8 | الدليل الرئيسي الذي يحتوي على منطق التطبيق. يشمل الملفات الأساسية التالية:
9 |
10 | ### **📄 configuration.ts**
11 | يحتوي على جميع إعدادات التطبيق للإطار. يقوم بتهيئة الخدمات العامة والإعدادات الأساسية التي يحتاجها مختلف الوحدات في التطبيق.
12 |
13 | ### **📄 provider.ts**
14 | يشمل تعريف **المزود** الذي يمتد من `BaseProvider`، وهو مسؤول عن تهيئة وربط جميع الوحدات. يتضمن الملف الوظائف التالية:
15 |
16 | - **register()**: يتم استدعاؤه عند بدء تشغيل الخادم والتطبيق، ويُستخدم لتسجيل وتهيئة الوحدات.
17 | - **boot()**: يتم استدعاؤه مع كل طلب وارد، ويُستخدم لتهيئة أي خدمات أو إعدادات إضافية يحتاجها كل طلب.
18 |
19 | ### **📂 modules**
20 | يحتوي على الوحدات المختلفة داخل التطبيق. كل وحدة هي مجلد يحتوي على المكونات الأساسية مثل:
21 |
22 | - **📂 controllers**: يحتوي على المنطق الذي يتحكم في العمليات داخل الوحدة.
23 | - **📂 services**: يحتوي على الخدمات أو المنطق التجاري الخاص بالوحدة.
24 | - **📂 repositories**: مخصص للتفاعل مع قواعد البيانات أو التعامل مع البيانات.
25 | - **📄 module.ts**: الملف الرئيسي للوحدة الذي يقوم بتهيئة وربط الوحدة في التطبيق، ويتعامل مع وظائفها الأساسية.
26 |
27 | ## **📂 storage**
28 | يحتوي على مجلدات مخصصة لتخزين الملفات:
29 |
30 | ### **📂 private**
31 | يخزن جميع الملفات الحساسة التي يجب أن تظل محمية. يشمل الملفات التي يجب ألا تكون متاحة لأي طرف آخر.
32 |
33 | ### **📂 public**
34 | يخزن الملفات التي يمكن للجميع الوصول إليها من خلال التطبيق. هذه الملفات متاحة للاستخدام العام.
35 |
36 | ## **📄 .env**
37 | ملف البيئة الذي يحتوي على المتغيرات الحساسة الخاصة بالتطبيق، مثل مفاتيح الـ API، إعدادات الاتصال بقاعدة البيانات، وأي معلومات حساسة يجب أن تظل سرية.
38 |
39 | ---
40 |
41 | ## **🔑 النقاط الرئيسية**
42 |
43 | - **configuration.ts**: يحتوي على إعدادات تهيئة الإطار والتطبيق.
44 | - **provider.ts**: يحتوي على منطق المزود وتسجيل الوحدات.
45 | - **modules**: يحتوي على الوحدات التي تشمل **controllers** و **services** و **repositories**.
46 | - **storage**: يميز بين الملفات العامة والخاصة من خلال مجلدات **private** و **public**.
47 | - **.env**: لتخزين المتغيرات الحساسة المستخدمة في بيئة التطبيق.
48 |
49 | ---
50 |
51 | تم تصميم هيكل الدليل في **كوكب** لتوفير بيئة تطوير مرنة وآمنة، مما يضمن أداءً عاليًا وسهولة التوسع في التطبيقات المستقبلية.
--------------------------------------------------------------------------------
/pages/ar/getting-started/environment-variables.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "إدارة متغيرات البيئة باستخدام Kawkab"
3 | description: "دليل شامل لإدارة متغيرات البيئة باستخدام إطار العمل Kawkab."
4 | ---
5 |
6 | # **إدارة متغيرات البيئة باستخدام Kawkab**
7 |
8 | يوفر إطار العمل **كوكب** طريقة مريحة وفعالة للتعامل مع متغيرات البيئة بسهولة، مع دعم القيم الافتراضية وتحويل الأنواع مثل السلاسل النصية، والأرقام، والقيم البوليانية، بالإضافة إلى القيم المعقدة مثل JSON والقوائم.
9 |
10 | ---
11 |
12 | ## **التهيئة والاستخدام**
13 |
14 | ### **1. إعداد ملف البيئة**
15 | عند تثبيت المشروع، ستجد ملفًا باسم `.env.example` في جذر المشروع. يعمل هذا الملف كقالب لمتغيرات البيئة التي يمكنك استخدامها في بيئات التطوير والإنتاج.
16 |
17 | - لإنشاء الملفات اللازمة لكل بيئة، استخدم الأمر التالي:
18 |
19 | ```bash
20 | npm run kawkab env
21 | ```
22 |
23 | سيقوم هذا الأمر بإنشاء الملفات التالية:
24 |
25 | - `.env.development`
26 | - `.env.production`
27 |
28 | ### **2. مثال على محتوى ملف البيئة**
29 |
30 | ```ini
31 | # معلومات التطبيق
32 | APP_NAME="Kawkab App"
33 | APP_DEBUG=true
34 | APP_MAINTENANCE_MODE=false
35 |
36 | # إعدادات الخادم
37 | SERVER_URL=http://localhost
38 | SERVER_PORT=3000
39 |
40 | # إعدادات قاعدة البيانات
41 | DATABASE_CLIENT=mysql
42 | DATABASE_HOST=127.0.0.1
43 | DATABASE_PORT=3306
44 | DATABASE_USER=root
45 | DATABASE_PASSWORD=
46 | DATABASE_NAME=kawkab
47 |
48 | # إعدادات اللغة
49 | LOCALE_CODE=en
50 |
51 | # إعدادات البريد الإلكتروني
52 | MAIL_HOST=sandbox.smtp.example.io
53 | MAIL_PORT=587
54 | MAIL_USER=
55 | MAIL_PASS=
56 | MAIL_TLS=false
57 | MAIL_FROM_ADDRESS="hello@example.com"
58 | MAIL_FROM_NAME="${APP_NAME}"
59 | ```
60 |
61 | **ملاحظات:**
62 | - يمكن كتابة القيم مع أو بدون علامات اقتباس.
63 | - يمكن استخدام التعليقات داخل الملف باستخدام `#`.
64 | - لدعم القيم الديناميكية، يمكن الإشارة إلى متغير آخر باستخدام `${key}` كما في المثال.
65 |
66 | ---
67 |
68 | ## **3. قراءة متغيرات البيئة**
69 |
70 | ### **الحصول على قيمة نصية**
71 | للحصول على قيمة نصية من متغير بيئة:
72 |
73 | ```tsx
74 | const appName = env.get("APP_NAME", "DefaultApp");
75 | console.log(`اسم التطبيق: ${appName}`);
76 | ```
77 |
78 | **الشرح:**
79 | - إذا لم يتم تعريف `APP_NAME` في البيئة، سيتم استخدام القيمة الافتراضية `"DefaultApp"`.
80 |
81 | ### **الحصول على قيمة بوليانية**
82 | للحصول على قيمة بوليانية:
83 |
84 | ```tsx
85 | const isDebug = env.bool("APP_DEBUG");
86 | console.log(`وضع التصحيح: ${isDebug}`);
87 | ```
88 |
89 | **الشرح:**
90 | - تعيد طريقة `bool` القيمة `true` إذا كانت القيمة `"true"` أو `"1"`، و `false` خلاف ذلك.
91 |
92 | ### **الحصول على قيمة رقمية**
93 | للحصول على قيمة رقمية:
94 |
95 | ```tsx
96 | const serverPort = env.number("SERVER_PORT", 3000);
97 | console.log(`منفذ الخادم: ${serverPort}`);
98 | ```
99 |
100 | **الشرح:**
101 | - إذا لم يتم تعريف `SERVER_PORT`، سيتم استخدام القيمة الافتراضية `3000`.
102 |
103 | ---
104 |
105 | ## **4. التعامل مع القيم المعقدة**
106 |
107 | ### **الحصول على قيمة JSON**
108 | إذا كان لديك متغير يحتوي على بيانات JSON:
109 |
110 | ```tsx
111 | const databaseConfig = env.json("DATABASE_CONFIG", { host: "localhost" });
112 | console.log(databaseConfig);
113 | ```
114 |
115 | **الشرح:**
116 | - إذا لم يتم تعريف `DATABASE_CONFIG`، سيتم استخدام الكائن الافتراضي `{ host: "localhost" }`.
117 |
118 | ### **الحصول على قائمة من القيم**
119 | إذا كان لديك قائمة مفصولة بفواصل:
120 |
121 | ```tsx
122 | const supportedLocales = env.array("SUPPORTED_LOCALES", ",", ["en", "ar"]);
123 | console.log(`اللغات المدعومة: ${supportedLocales}`);
124 | ```
125 |
126 | **الشرح:**
127 | - يتم تحويل السلسلة إلى مصفوفة بناءً على الفاصل (`,` في المثال).
128 |
129 | ---
130 |
131 | ## **5. تعديل متغيرات البيئة**
132 |
133 | ### **إضافة متغير جديد**
134 | لإضافة متغير بيئة جديد بشكل ديناميكي:
135 |
136 | ```tsx
137 | env.set("NEW_FEATURE", "enabled");
138 | console.log(env.get("NEW_FEATURE")); // الإخراج: "enabled"
139 | ```
140 |
141 | ### **حذف متغير بيئة**
142 | لحذف متغير بيئة:
143 |
144 | ```tsx
145 | env.delete("TEMP_VARIABLE");
146 | console.log(env.has("TEMP_VARIABLE")); // الإخراج: false
147 | ```
148 |
149 | ---
150 |
151 | ## **الختام**
152 | يجعل إطار العمل **كوكب** من السهل إدارة متغيرات البيئة بطريقة مرنة وبسيطة. يوفر الأدوات اللازمة للحصول على وتحويل القيم بسهولة، مع دعم القيم الافتراضية، مما يجعله خيارًا مثاليًا للمطورين الذين يبحثون عن حلول فعالة لإدارة بيئات التطبيقات.
--------------------------------------------------------------------------------
/pages/ar/getting-started/file-based-routing.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: التوجيه المبني على الملفات
3 | description: شرح كيفية عمل نظام التوجيه المبني على الملفات في إطار العمل كوكب Kawkab
4 | ---
5 |
6 | # التوجيه المبني على الملفات في كوكب
7 |
8 | يستخدم كوكب نظام التوجيه المبني على الملفات (File-Based Routing)، وهو نهج يجعل إنشاء وإدارة مسارات التطبيق أكثر سهولة وبداهة.
9 |
10 | ## كيف يعمل؟
11 |
12 | في كوكب، يتم تحديد المسارات تلقائياً بناءً على هيكل الملفات في مجلد `controllers`. كل ملف في هذا المجلد يمثل مساراً في تطبيقك.
13 |
14 | ### مثال بسيط
15 |
16 | ```
17 | app/
18 | └── main/
19 | └── controllers/
20 | ├── index.ts // يمثل "/"
21 | ├── about.ts // يمثل "/about"
22 | └── users/
23 | ├── index.ts // يمثل "/users"
24 | └── [id].ts // يمثل "/users/:id"
25 | ```
26 |
27 | ## أنواع المسارات
28 |
29 | ### 1. المسارات الثابتة
30 | ```typescript
31 | // app/modules/main/controllers/about.ts
32 |
33 | import { BaseController, req } from "kawkab";
34 |
35 | export default class extends BaseController {
36 | get() {
37 | return {
38 | message: "صفحة حول"
39 | }
40 | }
41 | }
42 | ```
43 |
44 | ### 2. المسارات الديناميكية
45 | ```typescript
46 | // app/modules/main/controllers/users/[id].ts
47 |
48 | import { BaseController, req } from "kawkab";
49 |
50 | export default class extends BaseController {
51 | get() {
52 | const userId = req.var('id');
53 | return {
54 | message: `عرض المستخدم رقم ${userId}`
55 | }
56 | }
57 | }
58 | ```
59 |
60 | ### 3. المسارات المتداخلة
61 | ```typescript
62 | // app/modules/main/controllers/blog/[category]/[post].ts
63 |
64 | import { BaseController, req } from "kawkab";
65 |
66 | export default class extends BaseController {
67 | get() {
68 | const { category, post } = req.vars();
69 | return {
70 | category,
71 | post
72 | }
73 | }
74 | }
75 | ```
76 |
77 | ## طرق HTTP المدعومة
78 |
79 | يدعم كوكب جميع طرق HTTP الرئيسية:
80 |
81 | ```typescript
82 | export default class extends BaseController {
83 | // GET /users
84 | get() {
85 | return { message: "قائمة المستخدمين" }
86 | }
87 |
88 | // POST /users
89 | post() {
90 | return { message: "إنشاء مستخدم جديد" }
91 | }
92 |
93 | // PUT /users
94 | put() {
95 | return { message: "تحديث المستخدم" }
96 | }
97 |
98 | // DELETE /users
99 | delete() {
100 | return { message: "حذف المستخدم" }
101 | }
102 | }
103 | ```
104 | ## أفضل الممارسات
105 |
106 | 1. **تنظيم المسارات**
107 | - استخدم مجلدات منطقية لتجميع المسارات المتعلقة
108 | - حافظ على تسلسل هرمي واضح
109 |
110 | 2. **تسمية الملفات**
111 | - استخدم أسماء واضحة ووصفية
112 | - استخدم الأقواس المربعة للمتغيرات `[id]`
113 |
114 | 3. **التعامل مع الأخطاء**
115 | - قم بمعالجة الحالات الاستثنائية
116 | - استخدم رموز الحالة HTTP المناسبة
117 |
118 | ## مثال متكامل
119 |
120 | ```typescript
121 | // app/modules/main/controllers/api/products/[id]/reviews/[reviewId].ts
122 |
123 | import { BaseController, req } from "kawkab";
124 |
125 | export default class extends BaseController {
126 | // GET /api/products/1/reviews/5
127 | get() {
128 | const { id, reviewId } = req.vars();
129 | return {
130 | productId: id,
131 | reviewId: reviewId,
132 | message: "عرض مراجعة محددة لمنتج محدد"
133 | }
134 | }
135 |
136 | // POST /api/products/1/reviews
137 | post() {
138 | const { id } = req.vars();
139 | return {
140 | message: `إضافة مراجعة جديدة للمنتج ${id}`
141 | }
142 | }
143 | }
144 | ```
145 |
146 | ## الخاتمة
147 |
148 | التوجيه المبني على الملفات في كوكب يوفر:
149 | - تنظيم أفضل للكود
150 | - سهولة في الفهم والصيانة
151 | - مرونة في إدارة المسارات
152 | - دعم للمسارات الديناميكية والمتداخلة
153 |
--------------------------------------------------------------------------------
/pages/ar/getting-started/hmvc-architecture.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: نمط HMVC في كوكب Kawkab
3 | description: شرح مبسط لنمط HMVC في إطار العمل كوكب Kawkab وكيفية استخدام الوحدات
4 | ---
5 |
6 | # **نمط HMVC في كوكب Kawkab**
7 |
8 | نمط HMVC (Hierarchical Model-View-Controller) هو امتداد لنمط MVC التقليدي، حيث يتم تنظيم التطبيق في وحدات مستقلة. في كوكب، كل وحدة تحتوي على الـ MVC الخاص بها.
9 |
10 | ## مفهوم HMVC
11 |
12 | ### ما هو HMVC؟
13 | - **H** تعني Hierarchical (هرمي)
14 | - **MVC** هي نفس المكونات الأساسية (النموذج، العرض، المتحكم)
15 | - كل وحدة تعمل بشكل مستقل
16 | - يمكن للوحدات التواصل مع بعضها البعض
17 |
18 | ## هيكل الوحدات
19 |
20 | ```
21 | app/
22 | └── main/
23 | └── controllers/
24 | ├── index.ts // يمثل "/"
25 | ├── about.ts // يمثل "/about"
26 | └── users/
27 | ├── index.ts // يمثل "/users"
28 | └── [id].ts // يمثل "/users/:id"
29 | ```
30 |
31 | ## أنواع المسارات
32 |
33 | ### 1. المسارات الثابتة
34 | ```typescript
35 | // app/modules/main/controllers/about.ts
36 |
37 | import { BaseController, req } from "kawkab";
38 |
39 | export default class extends BaseController {
40 | get() {
41 | return {
42 | message: "صفحة حول"
43 | }
44 | }
45 | }
46 | ```
47 |
48 | ### 2. المسارات الديناميكية
49 | ```typescript
50 | // app/modules/main/controllers/users/[id].ts
51 |
52 | import { BaseController, req } from "kawkab";
53 |
54 | export default class extends BaseController {
55 | get() {
56 | return {
57 | message: `المستخدم ${req.var('id')}`
58 | }
59 | }
60 | }
61 | ```
62 |
63 | ## إنشاء وحدة جديدة
64 |
65 | يمكنك إنشاء وحدة جديدة باستخدام الأمر:
66 |
67 | ```bash
68 | npm run kawkab module:make blog
69 | ```
70 |
71 | ## مثال على الوحدات
72 |
73 | ### 1. وحدة المدونة
74 | ```typescript
75 | // app/modules/blog/controllers/posts/index.ts
76 |
77 | import { BaseController, req } from "kawkab";
78 |
79 | export default class extends BaseController {
80 | get() {
81 | return {
82 | message: "مقالات المدونة",
83 | data: [
84 | { title: "المقال الأول" },
85 | { title: "المقال الثاني" }
86 | ]
87 | };
88 | }
89 | }
90 | ```
91 |
92 | ### 2. وحدة المتجر
93 | ```typescript
94 | // app/modules/shop/controllers/products/index.ts
95 |
96 | import { BaseController, req } from "kawkab";
97 |
98 | export default class extends BaseController {
99 | get() {
100 | return {
101 | message: "منتجات المتجر",
102 | data: [
103 | { name: "منتج 1" },
104 | { name: "منتج 2" }
105 | ]
106 | };
107 | }
108 | }
109 | ```
110 |
111 | ## مميزات HMVC في كوكب
112 |
113 | ### 1. تنظيم أفضل للكود
114 | - كل وحدة مستقلة بذاتها
115 | - سهولة إدارة المشاريع الكبيرة
116 | - تقسيم المنطق حسب الوظيفة
117 |
118 | ### 2. إعادة استخدام الكود
119 | - يمكن استخدام نفس الوحدة في مشاريع مختلفة
120 | - مشاركة الوظائف بين الوحدات
121 | - تقليل تكرار الكود
122 |
123 | ### 3. صيانة أسهل
124 | - تعديل وحدة لا يؤثر على الوحدات الأخرى
125 | - اختبار كل وحدة بشكل منفصل
126 | - تحديث الوظائف بسهولة
127 |
128 | ## أفضل الممارسات
129 |
130 | 1. **تقسيم منطقي للوحدات**
131 | - كل وحدة تمثل جزء مستقل من التطبيق
132 | - تجنب التداخل بين الوحدات
133 |
134 | 2. **الاستقلالية**
135 | - كل وحدة تعمل بشكل مستقل
136 | - تقليل الاعتماد بين الوحدات
137 |
138 | 3. **إعادة الاستخدام**
139 | - تصميم الوحدات بحيث يمكن إعادة استخدامها
140 | - مشاركة المكونات المشتركة
141 |
142 | ## الخاتمة
143 |
144 | نمط HMVC في كوكب يوفر:
145 | - تنظيم أفضل للمشاريع الكبيرة
146 | - مرونة في إدارة الوحدات
147 | - قابلية للتوسع والصيانة
148 | - إمكانية إعادة استخدام الكود
149 |
150 | يمكنك البدء باستخدام الوحدة الرئيسية `main` ثم إضافة وحدات جديدة حسب احتياجات مشروعك.
151 |
--------------------------------------------------------------------------------
/pages/ar/getting-started/installation.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: التثبيت
3 | ---
4 |
5 | # **دليل التثبيت لإطار العمل كوكب Kawkab**
6 |
7 | إطار العمل **كوكب Kawkab** يقدم لك بيئة تطوير مرنة وقوية لبناء تطبيقات ويب حديثة. في هذا الدليل، سنتناول خطوات تثبيت **كوكب Kawkab** عبر **Node.js** و **Bun**.
8 |
9 | ## **التثبيت عبر Node.js**
10 |
11 | ### **المتطلبات المبدئية:**
12 | قبل البدء، تأكد من أنك قد قمت بتثبيت **Node.js** و **npm** على جهازك. للحصول على النسخة المطلوبة، يمكنك تحميل **Node.js** من [الموقع الرسمي](https://nodejs.org/) مع التأكد من أنك تستخدم النسخة 18.0 أو أحدث.
13 |
14 | ### **إنشاء مشروع جديد باستخدام كوكب Kawkab:**
15 | لبدء مشروع جديد باستخدام **كوكب Kawkab**، قم بتشغيل الأمر التالي في الطرفية:
16 |
17 | ```bash
18 | npx create-kawkab-app@latest init my-kawkab-app
19 | ```
20 |
21 | سيقوم هذا الأمر بإنشاء مشروع جديد باسم `app` داخل مجلد منفصل يحتوي على جميع ملفات الإعدادات الخاصة بـ **كوكب Kawkab**.
22 |
23 | ### **الانتقال إلى مجلد المشروع:**
24 | بعد أن يتم إنشاء المشروع، قم بالانتقال إلى المجلد الذي تم إنشاؤه باستخدام الأمر التالي:
25 |
26 | ```bash
27 | cd my-kawkab-app
28 | ```
29 |
30 | ### **تشغيل خادم التطوير:**
31 | لتشغيل خادم التطوير المحلي الخاص بـ **كوكب Kawkab**، استخدم الأمر التالي:
32 |
33 | ```bash
34 | npm run dev
35 | ```
36 |
37 | سيتم تشغيل خادم التطوير على الرابط المحلي `http://localhost:3000`، مما يمكنك من معاينة تطبيقك وتجربة جميع الميزات بشكل فوري.
38 |
39 | ---
40 |
41 | الآن أصبح لديك تطبيق جاهز! **كوكب Kawkab** يوفر لك العديد من الأدوات والميزات المدمجة التي تساعدك على بناء تطبيقات ويب عالية الجودة بسرعة وكفاءة.
42 |
43 | ## **التثبيت عبر Bun**
44 |
45 | إذا كنت تفضل استخدام **Bun** كـ **JavaScript runtime** سريع وفعّال، يمكنك تثبيت **كوكب Kawkab** باستخدام **Bun CLI** باتباع الخطوات التالية:
46 |
47 | ### **إنشاء مشروع جديد باستخدام كوكب Kawkab عبر Bun:**
48 |
49 | ```bash
50 | bunx create-kawkab-app@latest init my-kawkab-app
51 | ```
52 |
53 | بقية الخطوات مشابهة تمامًا لما تم شرحه في التثبيت عبر **Node.js**.
54 |
55 | ---
56 |
57 | ## **الختام**
58 |
59 | الآن يمكنك اختيار الطريقة الأنسب لك لبدء بناء تطبيقك باستخدام **كوكب Kawkab**. سواء كنت تستخدم **Node.js** أو **Bun**، يقدم لك هذا الإطار بيئة تطوير متكاملة لبناء تطبيقات ويب حديثة، مرنة، وقابلة للتوسع.
60 |
61 | ابدأ الآن واستمتع بتجربة تطوير سلسة وقوية!
--------------------------------------------------------------------------------
/pages/ar/getting-started/mvc-architecture.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: نمط MVC في كوكب Kawkab
3 | description: شرح مبسط لنمط MVC في إطار العمل كوكب Kawkab
4 | ---
5 |
6 | # نمط MVC في كوكب Kawkab
7 |
8 | نمط MVC هو نمط تصميم يقسم التطبيق إلى ثلاثة أجزاء رئيسية. في كوكب، يمكنك استخدام الوحدة الرئيسية `main` للبدء بتطبيق هذا النمط مباشرة، حيث تأتي مع التطبيق افتراضياً وتحتوي على كل ما تحتاجه.
9 |
10 | ## المكونات الرئيسية
11 |
12 | ### 1. النموذج (Model)
13 | - **M** تعني Model (النموذج)
14 | - يمثل البيانات وقواعد العمل
15 | - يتعامل مع قاعدة البيانات
16 | - مثال:
17 | ```typescript
18 | // app/modules/main/models/User.ts
19 | export class User extends Model {
20 | // يحتوي على تعريف البيانات وقواعد العمل
21 | }
22 | ```
23 |
24 | ### 2. العرض (View)
25 | - **V** تعني View (العرض)
26 | - يمثل واجهة المستخدم
27 | - يعرض البيانات للمستخدم
28 | - مثال:
29 | ```typescript
30 | {
31 | "message": "مرحباً",
32 | "data": {
33 | "name": "أحمد",
34 | "email": "ahmed@example.com"
35 | }
36 | }
37 | ```
38 |
39 | ### 3. المتحكم (Controller)
40 | - **C** تعني Controller (المتحكم)
41 | - يستقبل طلبات المستخدم
42 | - يتحكم في تدفق البيانات
43 | - مثال:
44 | ```typescript
45 | // app/modules/main/controllers/users/index.ts
46 | export default class extends BaseController {
47 | // يستقبل الطلبات ويتعامل معها
48 | get() {
49 | return {
50 | message: "مرحباً",
51 | data: {
52 | name: "أحمد",
53 | email: "ahmed@example.com"
54 | }
55 | };
56 | }
57 | }
58 | ```
59 |
60 | ## هيكل المجلدات في main
61 | ```
62 | app/
63 | ├── main/ # الوحدة الرئيسية - تأتي جاهزة مع التطبيق
64 | │ ├── controllers/ # المتحكمات (C)
65 | │ ├── models/ # النماذج (M)
66 | │ └── views/ # العرض (V)
67 | ```
68 |
69 | ## البدء السريع مع main
70 |
71 | يمكنك البدء مباشرة باستخدام نمط MVC عن طريق الوحدة `main`:
72 | 1. النماذج: ضع نماذجك في `main/models`
73 | 2. المتحكمات: أضف متحكماتك في `main/controllers`
74 | 3. العرض: قم بتنسيق البيانات في المتحكمات
75 |
76 | ## الخاتمة
77 |
78 | نمط MVC في كوكب يساعد في:
79 | - تنظيم الكود بشكل منطقي
80 | - فصل المسؤوليات بين المكونات
81 | - سهولة الصيانة والتطوير
82 |
83 | مع وحدة `main` الافتراضية، يمكنك البدء بتطوير تطبيقك فوراً دون الحاجة لإعداد إضافي.
84 |
--------------------------------------------------------------------------------
/pages/ar/getting-started/production.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: الإنتاج
3 | ---
4 |
5 | # **التحضير للإنتاج في إطار العمل كوكب Kawkab**
6 |
7 | بعد الانتهاء من تطوير تطبيقك باستخدام **كوكب Kawkab**، ستحتاج إلى تشغيله في بيئة الإنتاج. هذا الدليل يشرح كيفية إعداد وتشغيل التطبيق باستخدام الأوامر المناسبة.
8 |
9 | ---
10 |
11 | ## **1. إنشاء نسخة الإنتاج (Build)**
12 |
13 | لتحضير التطبيق ليعمل في بيئة الإنتاج، قم بإنشاء نسخة مضغوطة ومجهزة باستخدام الأمر التالي:
14 |
15 | ```bash
16 | npm run build
17 | ```
18 |
19 | هذا الأمر يقوم بـ:
20 |
21 | - تجهيز الملفات النهائية التي يتم تشغيلها على الخادم.
22 |
23 | ستُحفظ النسخة المولدة في المجلد `.dist`.
24 |
25 | ---
26 |
27 | ## **2. تشغيل التطبيق في بيئة الإنتاج**
28 |
29 | بعد الانتهاء من البناء، يمكنك تشغيل التطبيق في وضع الإنتاج باستخدام الأمر التالي:
30 |
31 | ```bash
32 | npm run start
33 | ```
34 |
35 | ### **ما يفعله هذا الأمر:**
36 | - يقوم بتحميل النسخة النهائية من المشروع.
37 | - يبدأ تشغيل خادم الإنتاج.
38 | - يجعل التطبيق متاحًا على العنوان المحدد (عادةً `http://localhost:3000`).
39 |
40 | ---
41 |
42 | ## **3. نصائح هامة لبيئة الإنتاج**
43 |
44 | ### **إعدادات البيئة:**
45 | تأكد من أن ملف البيئة `.env.production` يحتوي على الإعدادات المناسبة للإنتاج.
46 |
47 | ### **خادم الويب العكسي (Reverse Proxy):**
48 | لتحسين الأداء والأمان، يمكنك وضع خادم الويب مثل **Nginx** أو **Apache** كوكيل عكسي أمام تطبيقك.
49 |
50 | ---
51 |
52 | ## **الختام**
53 |
54 | بمجرد تشغيل التطبيق في وضع الإنتاج، سيكون جاهزًا للتعامل مع المستخدمين. إطار العمل **كوكب Kawkab** يقدم لك أدوات مرنة وفعّالة لضمان أداء عالٍ وتجربة مستخدم متميزة.
55 |
56 | استمتع بالإنتاجية مع **كوكب Kawkab**! 🚀
--------------------------------------------------------------------------------
/pages/ar/preface/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'faqs': {
3 | title: 'الأسئلة الشائعة',
4 | },
5 | 'governance': {
6 | title: 'الأدوار والمسؤوليات',
7 | },
8 | 'releases': {
9 | title: 'الإصدارات',
10 | },
11 | 'contribution-guide': {
12 | title: 'دليل المساهمة',
13 | },
14 | }
--------------------------------------------------------------------------------
/pages/ar/preface/contribution-guide.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "إرشادات المساهمة"
3 | description: "إرشادات المساهمة العامة لجميع المشاريع في إطار العمل كوكب Kawkab"
4 | ---
5 |
6 | # 🌟 **إرشادات المساهمة في كوكب Kawkab**
7 |
8 | نحن نرحب بالمساهمات في جميع مشاريع **كوكب Kawkab**. قبل المساهمة، يرجى قراءة هذه الإرشادات بعناية.
9 |
10 | ## طرق المساهمة
11 | البرمجة ليست الطريقة الوحيدة للمساهمة. إليك بعض الطرق الأخرى للمساهمة في المشروع والمجتمع:
12 |
13 | - إصلاح الأخطاء الطباعية في الوثائق
14 | - تحسين الوثائق الحالية
15 | - كتابة مقالات تعليمية أو تدوينات لزيادة الوعي بين الأعضاء
16 | - المساعدة في تصنيف المشكلات
17 | - مشاركة رأيك في المشكلات الحالية
18 | - المساعدة في المجتمع عبر Discord أو منتدى المناقشات
19 | - الإبلاغ عن الأخطاء
20 |
21 | ## الإبلاغ عن الأخطاء
22 | عادةً ما تكون العديد من المشاكل التي يتم الإبلاغ عنها في المشاريع مفتوحة المصدر عبارة عن أسئلة أو أخطاء في الإعداد من جانب المستخدم. لذلك نوصي بشدة بالتحقق من المشكلة بشكل صحيح قبل الإبلاغ عنها.
23 |
24 | ### كيفية الإبلاغ عن مشكلة:
25 | - **مشكلة مثالية**: تقوم بعزل الخطأ الأساسي. تقوم بإنشاء اختبار فاشل داخل المستودع وفتح مشكلة على GitHub حوله.
26 | - **مشكلة جيدة**: تقوم بعزل الخطأ الأساسي وتوفير إعادة إنتاج بسيطة له على مستودع GitHub.
27 | - **مشكلة معقولة**: تقوم بتحديد المشكلة بشكل صحيح وتشارك الشيفرة البرمجية التي تسببت في المشكلة.
28 |
29 | ## البدء في المساهمة
30 | إذا كنت ترغب في تقديم مساهمة من خلال "طلب سحب" (Pull Request)، يفضل أن تبدأ بمناقشة لفهم المشروع بشكل أكبر قبل البدء في العمل على الشيفرة البرمجية.
31 |
32 | - إذا كنت تصلح خطأ: يجب أن يكون الطلب قد تم تأكيد الخطأ.
33 | - إذا كنت تضيف ميزة جديدة: يرجى شرح سبب الحاجة لهذه الميزة.
34 |
35 | ## إعداد المستودع
36 | للبدء، قم بتقليد المستودع إلى جهازك المحلي:
37 |
38 | ```bash
39 | git clone
40 | npm install
41 | ```
42 |
43 | لتشغيل الاختبارات:
44 |
45 | ```bash
46 | npm test
47 | ```
48 |
49 | ## الأدوات المستخدمة
50 | إليك الأدوات التي يتم استخدامها في جميع المشاريع:
51 |
52 | | الأداة | الاستخدام |
53 | |----------------|------------------------------------------------|
54 | | TypeScript | جميع المستودعات مكتوبة بـ TypeScript. |
55 | | ESLint | لضمان الاتساق في أسلوب الكتابة عبر المستودعات. |
56 | | Prettier | لتنسيق الشيفرة البرمجية بشكل موحد. |
57 |
58 | ## تنسيق الكود
59 | قبل دفع الشيفرة إلى المستودع، تأكد من تنسيقها باستخدام الأدوات التالية:
60 |
61 | - لتنسيق الكود باستخدام Prettier:
62 | ```bash
63 | npm run format
64 | ```
65 | - لفحص الكود باستخدام ESLint:
66 | ```bash
67 | npm run lint
68 | ```
69 |
70 | ## كيف تحصل على التقدير كمساهم
71 | نحن نعتمد على GitHub لعرض جميع المساهمين في المستودع. إذا كانت مساهمتك كبيرة، سيتم تضمين اسمك في سجل الإصدارات.
--------------------------------------------------------------------------------
/pages/ar/preface/faqs.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "الأسئلة الشائعة"
3 | description: "إجابات على الأسئلة الأكثر شيوعًا حول كوكب Kawkab"
4 | ---
5 |
6 | # ❓ **الأسئلة الشائعة (FAQs)**
7 |
8 | ### من الذي يطور كوكب Kawkab؟
9 | **كوكب Kawkab** هو إطار عمل مفتوح المصدر تم تطويره بواسطة **@Hassan Kerdash** . الإطار يتم صيانته وتطويره بشكل مستمر بواسطة فريق العمل الأساسي والمساهمين من المجتمع.
10 |
11 | المطور الرئيسي، **@Hassan Kerdash**، هو قائد المشروع ويعمل بإستمرار على تطوير الإطار.
12 |
13 | ### كيف يتم تمويل كوكب Kawkab؟
14 | كوكب Kawkab هو مشروع مفتوح المصدر يتم تمويله من خلال التبرعات والمساهمات المجتمعية. إذا كنت أو شركتك تستفيد من استخدام كوكب Kawkab، يمكنك دعم المشروع من خلال التبرع عبر منصات مثل **PayPal** أو **Patreon**.
15 |
16 | ### هل كوكب Kawkab موثوق ويتم صيانته بشكل جيد؟
17 | نعم! كوكب Kawkab يتم استخدامه من قبل العديد من المطورين والشركات حول العالم. يقوم المطور الرئيسي بمتابعة تطوير وصيانة الإطار بشكل دوري لضمان الجودة والأداء العالي.
18 |
19 | نحن نواصل العمل على تحسين الوثائق، وإضافة ميزات جديدة، وتحسين قاعدة الكود.
20 |
21 | ### هل كوكب Kawkab سريع؟
22 | نعم، نركز في كوكب Kawkab على حل المشاكل الحقيقية بدلاً من السعي وراء تحقيق أفضل أداء في الاختبارات. لكننا نعمل دائمًا على تحسين أداء الإطار في المجالات الأكثر أهمية. على سبيل المثال:
23 |
24 | - خادم HTTP في كوكب Kawkab يعد من حيث الأداء على قدم المساواة مع العديد من الإطارات المعروفة مثل Fastify.
25 | - طبقة التحقق في كوكب Kawkab توفر أداءً أفضل من العديد من مكتبات التحقق الأخرى في بيئة **Node.js**.
26 |
27 | ### هل تقدمون دعمًا مدفوعًا؟
28 | نعم، نحن نقدم دعمًا مميزًا للمشاريع التي تحتاج إلى استشارة أو مساعدة إضافية. يمكنك معرفة المزيد حول برنامج الدعم الأولوي عبر [صفحتنا على GitHub](https://github.com/HassanKerdash/kawkab).
29 |
30 | ### كيف أبقى على اطلاع دائم مع كوكب Kawkab؟
31 | يمكنك متابعة كوكب Kawkab عبر الروابط التالية للبقاء على اطلاع بأحدث التحديثات:
32 |
33 | - [Discord server](https://discord.gg)
34 | - [X (Twitter)](https://twitter.com)
35 | - [GitHub discussions](https://github.com/HassanKerdash/kawkab/discussions)
36 | - [المدونة والنشرة الإخبارية](https://blog.kawkab.io)
37 |
38 | © كوكب Kawkab
39 |
--------------------------------------------------------------------------------
/pages/ar/preface/governance.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "إدارة كوكب Kawkab"
3 | description: "الأدوار والمسؤوليات داخل مشروع كوكب Kawkab"
4 | ---
5 |
6 | # 🏛️ **إدارة كوكب Kawkab**
7 |
8 | ### **المؤلفون**
9 | **@Hassan Kerdash** هو مؤلف **كوكب Kawkab** وهو المسؤول عن إدارة المشروع وتحديد معايير التطوير والاتجاه العام للمشروع. يلخص ذلك ما يلي:
10 |
11 | - المؤلف هو من يقرر المشاريع الجديدة التي ستنضم إلى إطار كوكب Kawkab.
12 | - المؤلف هو من يحدد المسؤولين عن المشاريع، ويوجههم حسب الحاجة، ويتولى نقل المشاريع إلى قائد آخر عندما يتنحى القائد الحالي.
13 | - من مسؤوليات المؤلف توثيق الرؤية العامة للإطار ومشاركة هذه الرؤية مع باقي القادة والمجتمع.
14 |
15 | ### **قادة المشاريع**
16 | كوكب Kawkab يتكون من مجموعة من الحزم التي تم إنشاؤها وإدارتها من قبل الفريق الأساسي. كل حزمة لها قائد مشروع يتم تعيينه من قبل المؤلف.
17 |
18 | في معظم الحالات، يكون منشئ الحزمة هو قائد المشروع نظرًا لجهوده الأولية في إنجاز الفكرة.
19 |
20 | - القائد هو الشخص الذي يتخذ القرار النهائي في جميع جوانب المشروع.
21 | - القائد مسؤول عن وضع الأهداف الاستراتيجية للمشروع والتواصل بشكل واضح مع المجتمع.
22 | - كما يتعين على القائد التفاعل مع المجتمع لتلبية احتياجاته المتنوعة وضمان استمرارية المشروع على المدى الطويل.
23 |
24 | ### **الفريق الأساسي**
25 | أعضاء الفريق الأساسي هم المساهمون الذين قدموا العديد من المساهمات القيمة للمشروع، ويتم الاعتماد عليهم لكتابة الشيفرة البرمجية وإجراء المراجعات.
26 |
27 | - عادةً، يتم تكليف أعضاء الفريق الأساسي بمسؤوليات محددة، مثل إصلاح الأخطاء، أو تطوير ميزات جديدة، أو تحسين الوثائق.
28 | - ليس لديهم سلطة اتخاذ قرارات تخص المشروع ككل، لكنهم غالبًا ما يكون لهم تأثير كبير في مسار المشروع.
29 |
30 | ### **أعضاء الفريق الأساسي النشطين**
31 | الأعضاء النشطين في الفريق الأساسي يساهمون في المشروع بشكل منتظم، ويتحملون مسؤوليات مثل فحص المشكلات، إصلاح الأخطاء، أو تحسين الوثائق.
32 |
33 | ### **أعضاء الفريق الأساسي الشرفيين**
34 | بعض الأعضاء الذين قدموا مساهمات كبيرة في الماضي قد لا يتمكنون من المشاركة بمستوى مماثل في الوقت الحالي. هؤلاء الأعضاء يُكرمون بلقب "أعضاء الفريق الأساسي الشرفيين" ويمكنهم العودة للمساهمة متى شاءوا.
35 |
36 | ### **المساهمون**
37 | المساهمون هم أعضاء في المجتمع لم يسعوا ليصبحوا جزءًا من الفريق الأساسي، لكنهم يقدمون مساهمات قيمة مثل تقديم التقارير عن الأخطاء، إضافة ميزات جديدة، أو تحسين البنية التحتية للمشروع.
38 |
39 | المساهمة ليست مرتبطة باحتياج للالتزام أو مهارات محددة، ويمكن لأي شخص أن يصبح مساهمًا ببساطة من خلال العمل على مهام مفيدة للمشروع.
40 |
41 | ### **المستخدمون**
42 | المستخدمون هم الأعضاء الأكثر أهمية في المجتمع. بدونهم، لن يكون للمشروع أي غرض. يمكن لأي شخص أن يكون مستخدمًا، ولا توجد متطلبات محددة لذلك.
43 |
44 | المستخدمون يجب تشجيعهم على المشاركة في المجتمع، مثل نشر الكلمة حول المشروع أو تقديم الدعم المعنوي.
45 |
46 | ### **الدعم**
47 | نحن نشجع جميع المشاركين في المجتمع على توفير الدعم للمستخدمين الجدد. هذا الدعم يتم بشكل طوعي ومن خلال القنوات المخصصة للمشروع.
48 |
49 | ### **التبرعات المالية**
50 | في المشاريع مفتوحة المصدر، التبرعات المالية ليست بنفس أهمية المساهمة النشطة، ولكنها تظل وسيلة مهمة لبعض الأفراد أو المؤسسات الذين لا يملكون وقتًا ولكن لديهم قدرة مالية لدعم المشروع.
51 |
52 | يمكنك دعمنا من خلال التبرعات عبر منصات مثل **GitHub Sponsors**.
53 |
54 | ### **العلامة والملكية**
55 | **كوكب Kawkab** هو علامة تشير إلي إطار العمل تحت اسم **@Hassan Kerdash**. يجب عدم استخدام اسم كوكب Kawkab أو شعاره بطريقة قد تضلل المستخدمين أو تشير إلى ارتباط غير رسمي بالمشروع.
56 |
57 | ### **المشاريع تحت مظلة كوكب Kawkab**
58 | المشاريع التي تنضم إلى **كوكب Kawkab** تكون ملكًا فكريًا للمؤلف. بمجرد أن يتم إضافة مشروع تحت مظلة كوكب Kawkab، لا يمكن للقائد حذف أو التخلي عن المشروع.
59 |
--------------------------------------------------------------------------------
/pages/ar/preface/releases.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "الإصدارات"
3 | description: "أهم الإصدارات الأساسية والحزم المرتبطة بإطار العمل"
4 | ---
5 |
6 | # 🚀 **الإصدارات**
7 |
8 | فيما يلي أهم الإصدارات لإطار العمل والنظام البيئي للحزم التي يتم صيانتها من قبل فريق نواة **كوكب Kawkab**.
9 |
10 | | الحزمة | التغيير | تاريخ الإصدار |
11 | |--------------------------------|--------------------------------------------------------|--------------------|
12 | | `kawkab@1.0.0-alpha.1` | إصدار أولي من الإطار للتجربة والاستكشاف | 9 ديسمبر، 2024 |
13 | | `create-kawkab-app@1.0.0-alpha.1` | إصدار أولي لأداة تثبيت وإعداد الإطار | 9 ديسمبر، 2024 |
14 |
15 | ### ملاحظات حول الإصدارات
16 | - **إصدارات رئيسية**: تحتوي على تغييرات كبيرة قد تتطلب تعديل في الشيفرة.
17 | - **إصدارات فرعية**: تشمل تحسينات صغيرة أو ميزات جديدة.
18 | - **إصلاحات**: إصدار مخصص لإصلاح الأخطاء أو تحسينات الأداء.
19 |
20 | ### الدعم
21 | إذا كنت تواجه أي مشاكل أو لديك استفسارات حول الإصدارات، يمكنك التواصل معنا عبر قنوات الدعم الرسمية.
--------------------------------------------------------------------------------
/pages/ar/security/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'input-validation': {
3 | title: "التحقق من المدخلات",
4 | },
5 | 'encryption': {
6 | title: "التشفير",
7 | },
8 | 'hashing': {
9 | title: "التجزئة",
10 | },
11 | 'password': {
12 | title: "كلمات المرور",
13 | },
14 | 'rate-limiter': {
15 | title: "معدل الطلبات",
16 | },
17 | 'auth': {
18 | title: "المصادقة",
19 | },
20 | };
21 |
--------------------------------------------------------------------------------
/pages/ar/security/auth.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: خدمة JWT في كوكب Kawkab
3 | description: دليل شامل لاستخدام خدمة JWT في إطار العمل كوكب Kawkab للتحقق من الهوية وإدارة رموز الوصول.
4 | ---
5 |
6 | # **خدمة JWT في كوكب Kawkab**
7 |
8 | تقدم خدمة JWT في إطار العمل **كوكب Kawkab** حلاً متكاملاً لإدارة رموز الوصول (**JSON Web Tokens**). تتيح هذه الخدمة إنشاء وتحقق وتجديد رموز الوصول بطريقة آمنة وفعالة.
9 |
10 | ---
11 |
12 | ## **المميزات الرئيسية**
13 |
14 | - إنشاء رموز وصول ورموز تجديد
15 | - التحقق من صحة الرموز
16 | - تجديد رموز الوصول
17 | - استخراج الرموز من ترويسة التفويض
18 | - إدارة صلاحية الرموز
19 |
20 | ---
21 |
22 | ## **استخدام الخدمة**
23 |
24 | ### **1. استيراد الخدمة**
25 | ```typescript
26 | import { jwt as JWT } from 'kawkab';
27 |
28 | const jwt = new JWT('2h', '1h');
29 | ```
30 |
31 | - اول عامل هو مدة صلاحية رموز الوصول (مثلاً: "2h" يعني 2 ساعات), الافتراضية هي 2 ساعة.
32 | - ثاني عامل هو مدة صلاحية رموز التجديد (مثلاً: "1h" يعني 1 ساعة), الافتراضية هي 1 ساعة.
33 |
34 | - s: مدة صلاحية رموز الوصول بالثواني
35 | - m: مدة صلاحية رموز الوصول بالدقايق
36 | - h: مدة صلاحية رموز الوصول بالساعات
37 | - d: مدة صلاحية رموز الوصول باليوم
38 | - w: مدة صلاحية رموز الوصول بالاسبوعات
39 | - M: مدة صلاحية رموز الوصول بالشهر
40 | - y: مدة صلاحية رموز الوصول بالسنة
41 |
42 | ### **2. إنشاء رموز الوصول**
43 | ```typescript
44 | // تعريف بيانات المستخدم
45 | const userData = {
46 | userId: "123",
47 | email: "user@example.com",
48 | role: "admin"
49 | };
50 |
51 | // إنشاء رموز الوصول والتجديد
52 | const tokens = jwt.generate(userData);
53 |
54 | console.log(tokens);
55 | // النتيجة:
56 | // {
57 | // accessToken: "eyJhbGciOiJIUzI1...",
58 | // refreshToken: "eyJhbGciOiJIUzI1...",
59 | // expiresIn: 86400 // مدة الصلاحية بالثواني
60 | // }
61 | ```
62 |
63 | ### **3. التحقق من صحة رمز الوصول**
64 | ```typescript
65 | try {
66 | const token = "eyJhbGciOiJIUzI1..."; // رمز الوصول
67 | const payload = jwt.verify(token);
68 |
69 | console.log(payload);
70 | // النتيجة:
71 | // {
72 | // userId: "123",
73 | // email: "user@example.com",
74 | // role: "admin"
75 | // }
76 | } catch (error) {
77 | console.error('رمز وصول غير صالح');
78 | }
79 | ```
80 |
81 | ### **4. تجديد رمز الوصول**
82 | ```typescript
83 | try {
84 | const refreshToken = "eyJhbGciOiJIUzI1..."; // رمز التجديد
85 | const newTokens = jwt.refresh(refreshToken);
86 |
87 | console.log(newTokens);
88 | // النتيجة:
89 | // {
90 | // accessToken: "eyJhbGciOiJIUzI1...", // رمز وصول جديد
91 | // refreshToken: "eyJhbGciOiJIUzI1...", // رمز تجديد جديد
92 | // expiresIn: 86400
93 | // }
94 | } catch (error) {
95 | console.error('رمز تجديد غير صالح');
96 | }
97 | ```
98 |
99 | ### **5. استخراج الرمز من ترويسة التفويض**
100 | ```typescript
101 | try {
102 | const authHeader = "Bearer eyJhbGciOiJIUzI1...";
103 | const token = jwt.extract(authHeader);
104 |
105 | console.log(token); // "eyJhbGciOiJIUzI1..."
106 | } catch (error) {
107 | console.error('ترويسة تفويض غير صالحة');
108 | }
109 | ```
110 | ---
111 |
112 | ## **أفضل الممارسات**
113 |
114 | 1. **تخزين الرموز:**
115 | - تخزين رمز الوصول في ذاكرة المتصفح المؤقتة
116 | - تخزين رمز التجديد في مكان آمن (مثل httpOnly cookie)
117 |
118 | 2. **تجديد الرموز:**
119 | - تجديد رمز الوصول قبل انتهاء صلاحيته
120 | - استخدام رمز التجديد مرة واحدة فقط
121 |
122 | 3. **الأمان:**
123 | - استخدام HTTPS دائماً
124 | - تعيين مدة صلاحية مناسبة للرموز
125 | - عدم تخزين معلومات حساسة في الرمز
126 |
127 | ---
128 |
129 | ## **إعدادات الخدمة**
130 |
131 | الخدمة مهيأة مسبقاً بالإعدادات التالية:
132 |
133 | - **مدة صلاحية رمز الوصول:** يوم واحد (`2d`)
134 | - **مدة صلاحية رمز التجديد:** سبعة أيام (`1d`)
135 | - **المفتاح السري:** مشفر ومخزن بشكل آمن
136 | - **مفتاح التجديد:** مشفر ومخزن بشكل آمن
137 |
138 | ---
139 |
140 | ## **الخلاصة**
141 |
142 | توفر خدمة JWT في **كوكب Kawkab** حلاً شاملاً وآمناً لإدارة رموز الوصول. من خلال واجهة برمجة بسيطة وواضحة، يمكن للمطورين التحكم بشكل كامل في عملية المصادقة وإدارة جلسات المستخدمين.
--------------------------------------------------------------------------------
/pages/ar/security/password.mdx:
--------------------------------------------------------------------------------
1 | # التعامل مع **كلمات المرور Password** في كوكب Kawkab
2 |
3 | في عالم تطوير التطبيقات الحديثة، يُعتبر **حماية كلمات المرور** أمرًا بالغ الأهمية لضمان أمان بيانات المستخدمين. في إطار عمل **كوكب Kawkab**، نوفر دوال مخصصة لتشفير كلمات المرور والتحقق منها بسهولة وأمان.
4 |
5 | ---
6 |
7 | ## **ما هي عملية حماية كلمة المرور؟**
8 |
9 | عملية حماية كلمة المرور تتضمن تحويل النصوص العادية (Plain Text) الخاصة بكلمات المرور إلى **بصمات رقمية مشفرة** باستخدام خوارزميات قوية.
10 | ### مميزات هذه العملية:
11 | 1. **عدم قابلية القراءة**: كلمة المرور المُشفرة لا يمكن قراءتها مباشرة.
12 | 2. **ثبات الأمان**: تُستخدم خوارزميات آمنة لضمان حماية البيانات.
13 | 3. **التحقق السريع**: يُمكن التحقق من صحة كلمة المرور دون معرفة النص الأصلي.
14 |
15 | ---
16 |
17 | ## **وظائف كلمات المرور في كوكب Kawkab**
18 |
19 | ### 1. **`hash`**
20 | دالة تُستخدم لإنشاء **بصمة مشفرة لكلمة المرور**.
21 | - تستخدم خوارزميات متقدمة لإنشاء البصمة.
22 | - يُفضل استخدامها أثناء عملية التسجيل أو تحديث كلمة المرور.
23 |
24 | #### **مثال:**
25 | ```ts
26 | import { password } from "kawkab";
27 |
28 | const myPassword = "MySecurePassword123";
29 | const hashedPassword = await password.hash(myPassword);
30 |
31 | console.log(hashedPassword);
32 | // الناتج: سلسلة مشفرة مثل: "$2b$10$XfT...9lmJ"
33 | ```
34 |
35 | #### **خيارات إضافية:**
36 | يمكن تخصيص قوة التشفير (عدد الجولات - Salt Rounds) لضمان مزيد من الأمان.
37 | ```ts
38 | const strongHash = await password.hash(password, 12);
39 | ```
40 |
41 | ---
42 |
43 | ### 2. **`verify`**
44 | دالة تُستخدم لمقارنة كلمة المرور المُدخلة مع البصمة المُخزنة للتحقق من صحتها.
45 | - تُستخدم أثناء تسجيل الدخول أو العمليات التي تتطلب التحقق.
46 |
47 | #### **مثال:**
48 | ```ts
49 | import { password } from "kawkab";
50 |
51 | const myPassword = "MySecurePassword123";
52 | const hashedPassword = await password.hash(myPassword);
53 |
54 | const isValid = await password.verify(myPassword, hashedPassword);
55 |
56 | if (isValid) {
57 | console.log("كلمة المرور صحيحة.");
58 | } else {
59 | console.log("كلمة المرور غير صحيحة.");
60 | }
61 | ```
62 |
63 | ---
64 |
65 | ## **استخدامات عملية لكلمات المرور في التطبيقات**
66 |
67 | ### **1. تسجيل المستخدمين الجدد**
68 | عند تسجيل المستخدم، تُشفّر كلمة المرور قبل تخزينها في قاعدة البيانات.
69 | ```ts
70 | import { password } from "kawkab";
71 |
72 | async function registerUser(username: string, password: string) {
73 | const hashedPassword = password.hash(password);
74 | console.log(`تم تسجيل المستخدم ${username} بكلمة مرور مشفرة: ${hashedPassword}`);
75 | }
76 |
77 | registerUser("Hassan", "Password123!");
78 | ```
79 |
80 | ---
81 |
82 | ### **2. تسجيل الدخول**
83 | عند محاولة تسجيل الدخول، تُقارن كلمة المرور المدخلة بالبصمة المخزنة.
84 | ```ts
85 | import { password } from "kawkab";
86 |
87 | async function loginUser(inputPassword: string, storedHash: string) {
88 | const isMatch = await password.verify(inputPassword, storedHash);
89 |
90 | if (isMatch) {
91 | console.log("تم تسجيل الدخول بنجاح.");
92 | } else {
93 | console.log("كلمة المرور غير صحيحة.");
94 | }
95 | }
96 |
97 | // مثال
98 | loginUser("Password123!", "$2b$10$XfT...9lmJ");
99 | ```
100 |
101 | ---
102 |
103 | ## **مقارنة بين `hash` و `verify`**
104 |
105 | | الوظيفة | المدخلات | النتيجة | الاستخدام |
106 | |--------------|-----------------------------|---------------------|--------------------------------|
107 | | **`hash`** | كلمة المرور النصية | بصمة مشفرة | تشفير كلمات المرور عند التسجيل |
108 | | **`verify`** | كلمة المرور النصية + البصمة | `true` أو `false` | التحقق عند تسجيل الدخول |
109 |
110 | ---
111 |
112 | ## **نصائح عملية**
113 | - **لا تخزن كلمات المرور كنصوص عادية.** استخدم دائمًا الدالة `hash` لتشفيرها.
114 | - اجعل عدد جولات التشفير (Salt Rounds) بين 10-14 للحصول على توازن بين الأداء والأمان.
115 | - عند التحقق، استخدم الدالة `verify` فقط لمقارنة كلمات المرور.
116 |
117 | ---
118 |
119 | باستخدام وظائف **كوكب Kawkab** المخصصة لحماية كلمات المرور، يمكنك ضمان مستوى عالٍ من الأمان لمستخدميك والتقليل من المخاطر الأمنية.
--------------------------------------------------------------------------------
/pages/ar/security/rate-limiter.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Rate Limiter
3 | description: كيفية تكوين والتحكم في معدل الطلبات باستخدام نظام Rate Limiter في Kawkab JS.
4 | ---
5 |
6 | # محدد المعدل للطلبات Rate Limiter في Kawkab JS
7 |
8 | يتم استخدام **Rate Limiter** للتحكم في عدد الطلبات التي يمكن أن يرسلها العميل إلى الخادم في فترة زمنية محددة. يساعد ذلك على منع الهجمات مثل **Denial of Service (DoS)** ويحمي تطبيقك من الإفراط في استخدام الموارد بسبب الطلبات المفرطة من نفس العميل.
9 |
10 | ### تكوين Rate Limiter
11 |
12 | يمكنك تكوين إعدادات **Rate Limiter** من خلال ملف الإعدادات الرئيسي `app/configuration.ts`. يوفر هذا الملف التحكم الكامل في عدد الطلبات المسموح بها والفترة الزمنية لكل عميل.
13 |
14 | #### إعدادات Rate Limiter
15 |
16 | ```typescript
17 | import { env } from "kawkab";
18 | import { Provider } from "./provider";
19 |
20 | // Main configuration object for the application
21 | export const app = {
22 | // Rate limiter configuration
23 | rateLimiter: {
24 | // Enable or disable the rate limiter
25 | enable: true,
26 |
27 | // Maximum number of requests allowed within the defined time window
28 | maxRequests: 100,
29 |
30 | // Time window (in milliseconds) for rate limiting, default is 1 minute (60 * 1000)
31 | windowTime: 60 * 1000,
32 |
33 | // Error code sent when rate limit is exceeded
34 | code: "too-many-requests",
35 |
36 | // Message displayed when rate limit is exceeded
37 | message: "Too many requests. Please try again later.",
38 | },
39 | };
40 | ```
41 |
42 | ### شرح الإعدادات:
43 |
44 | - **`enable`**: يحدد ما إذا كان Rate Limiter مفعلًا أم لا. إذا كانت القيمة `true`، فسيتم تفعيل النظام. إذا كانت `false`، سيتم تعطيله.
45 | - **`maxRequests`**: الحد الأقصى لعدد الطلبات التي يمكن للمستخدم إرسالها في فترة زمنية معينة (تعرف بالفترة الزمنية `windowTime`).
46 | - **`windowTime`**: الفترة الزمنية (بالميلي ثانية) التي يتم خلالها تحديد معدل الطلبات. القيمة الافتراضية هي 60 ثانية (60,000 ميلي ثانية).
47 | - **`code`**: الرمز الذي سيتم إرساله كاستجابة عندما يتجاوز العميل الحد المسموح به للطلبات.
48 | - **`message`**: الرسالة التي سيتم عرضها للمستخدم عندما يتجاوز الحد المسموح به للطلبات.
49 |
50 | ### الخلاصة
51 |
52 | يساعد **Rate Limiter** في حماية تطبيقك من الهجمات التي تعتمد على إرسال عدد كبير من الطلبات في وقت قصير. من خلال إعدادات قابلة للتخصيص في `configuration.ts`, يمكنك تحديد الحد الأقصى للطلبات وفترة التوقيت التي يمكن خلالها إرسال الطلبات. هذا يحسن من أمان الخادم ويحسن تجربة المستخدم.
53 |
54 | ---
55 |
56 | **ملاحظة:** تأكد من أن إعدادات **Rate Limiter** متوافقة مع احتياجات تطبيقك ومع حجم حركة المرور التي تتوقعها.
--------------------------------------------------------------------------------
/pages/en/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'index': {
3 | title: "Home",
4 | },
5 | 'preface': {
6 | title: "Introduction",
7 | },
8 | "getting-started": {
9 | title: "Getting Started",
10 | },
11 | 'concepts': {
12 | title: "Concepts",
13 | },
14 | 'basics': {
15 | title: "Basics",
16 | },
17 | 'security': {
18 | title: "Security",
19 | },
20 | 'database': {
21 | title: "Database",
22 | },
23 | 'digging-deeper': {
24 | title: "Digging Deeper",
25 | },
26 | };
27 |
--------------------------------------------------------------------------------
/pages/en/basics/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'routing': {
3 | title: "Routing",
4 | },
5 | 'controllers': {
6 | title: "Controllers",
7 | },
8 | 'api-versioning': {
9 | title: "API Versioning",
10 | },
11 | "static-file-server": {
12 | title: "Static File Server",
13 | },
14 | 'service': {
15 | title: "Services",
16 | },
17 | 'repositories': {
18 | title: "Repositories",
19 | },
20 | 'resources': {
21 | title: "Resources",
22 | },
23 | 'middleware': {
24 | title: "Middleware",
25 | },
26 | 'requests': {
27 | title: "Requests",
28 |
29 | },
30 | 'response': {
31 | title: "Response",
32 | },
33 | 'mail': {
34 | title: "Mail",
35 | },
36 | 'events': {
37 | title: 'Events',
38 | },
39 | }
40 |
--------------------------------------------------------------------------------
/pages/en/basics/api-versioning.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: API Versioning in Kawkab
3 | description: A comprehensive guide to managing API versioning in the Kawkab framework.
4 | ---
5 |
6 | # **API Versioning**
7 |
8 | API versioning is an important practice in modern application development. It allows you to update your API while maintaining compatibility with legacy applications.
9 |
10 | ## **How to Organize Versions in Kawkab**
11 |
12 | The Kawkab framework supports API version management by organizing controllers in different directories for each version.
13 |
14 | ### **Suggested Directory Structure:**
15 |
16 | ```
17 | app/
18 | ├── users/
19 | │ ├── controllers/
20 | │ │ ├── v1/
21 | │ │ │ └── index.ts
22 | │ │ └── v2/
23 | │ │ └── index.ts
24 | ```
25 |
26 | ## **Creating a Controller for a Specific Version**
27 |
28 | ### **First Version (v1):**
29 | ```bash
30 | npm run kawkab controller:make users/v1/profile users
31 | ```
32 |
33 | ### **Second Version (v2):**
34 | ```bash
35 | npm run kawkab controller:make users/v2/profile users
36 | ```
37 |
38 | ## **Example of Different Version Controllers**
39 |
40 | ### **Version 1 (v1) Controller:**
41 |
42 | ```ts
43 | import { BaseController, inherit } from "kawkab";
44 |
45 | export default class extends inherit(BaseController) {
46 | get() {
47 | return {
48 | status: true,
49 | version: "1.0",
50 | data: {
51 | name: "User Name",
52 | email: "user@example.com"
53 | }
54 | };
55 | }
56 | }
57 | ```
58 |
59 | ### **Version 2 (v2) Controller:**
60 |
61 | ```ts
62 | import { BaseController, inherit } from "kawkab";
63 |
64 | export default class extends inherit(BaseController) {
65 | get() {
66 | return {
67 | status: true,
68 | version: "2.0",
69 | data: {
70 | name: "User Name",
71 | email: "user@example.com",
72 | profile: {
73 | avatar: "https://example.com/avatar.jpg",
74 | bio: "User bio"
75 | }
76 | }
77 | };
78 | }
79 | }
80 | ```
81 |
82 | ## **Accessing Different Versions**
83 |
84 | Different versions can be accessed through the following paths:
85 |
86 | ### **First Version:**
87 | ```
88 | http://localhost:3000/api/v1/users/profile
89 | ```
90 |
91 | ### **Second Version:**
92 | ```
93 | http://localhost:3000/api/v2/users/profile
94 | ```
95 |
96 | ## **Best Practices**
97 |
98 | 1. **Clear Documentation:** Clearly document changes between versions.
99 | 2. **Backward Compatibility:** Maintain older versions working for a transition period.
100 | 3. **Deprecation Notice:** Inform users about versions that will become deprecated.
101 | 4. **Support Duration:** Clearly define the support period for each version.
102 |
103 | ## **Summary**
104 |
105 | API versioning in Kawkab is handled flexibly and simply through:
106 | 1. Organizing controllers in version directories.
107 | 2. Supporting multiple versions simultaneously.
108 | 3. Maintaining compatibility.
109 |
--------------------------------------------------------------------------------
/pages/en/basics/events.mdx:
--------------------------------------------------------------------------------
1 | ### Events in Kawkab Framework
2 |
3 | Events are a fundamental part of building modern applications, where the Event Emitter mechanism allows you to interact with different parts of the application in a flexible and extensible way. In the Kawkab framework, developers can easily create events using CLI commands, which is a powerful way to add dynamic functionality to their applications.
4 |
5 | #### Creation Command
6 | To create a new event, you can use the following command:
7 |
8 | ```bash
9 | npm run kawkab event:make [module]
10 | ```
11 |
12 | - **``**: The name of the file to be created.
13 | - **``**: The name of the event to be triggered.
14 | - **`[module]`**: The module name (optional, will default to "main" if not specified).
15 |
16 | #### Example:
17 | Let's say you want to create an event that generates an OTP (One-Time Password) for a user, you can execute the following command:
18 |
19 | ```bash
20 | npm run kawkab event:make generateLoginOTP user
21 | ```
22 |
23 | #### Generated File Result:
24 | A new file named `generateLoginOTP.ts` will be created in the specified path (`app/main/events/user/generateLoginOTP.ts`). The file contents will be as follows:
25 |
26 | ```ts
27 | export default function (data: any) {
28 | console.log("Event triggered:", data);
29 | }
30 | ```
31 |
32 | #### Code Explanation:
33 | - **The `export default function`**: This is the function that gets executed when the event is triggered. This function receives `data` and prints it using `console.log`.
34 | - **`data`**: This is the object passed when triggering the event, and it can include any data you want to process.
35 |
36 | #### How to Use the Event:
37 | After creating the event, you can trigger it from anywhere within the application using the following code:
38 |
39 | ```ts
40 | import { event } from "kawkab";
41 |
42 | // Trigger the event
43 | event.emit('user');
44 | ```
45 |
46 | #### Passing Data with the Event:
47 | You can also pass data with the event using the following code:
48 |
49 | ```ts
50 | event.emit('user', { otp: '123456', userId: 1 });
51 | ```
52 |
53 | #### Conclusion:
54 | Events are a powerful way to organize work in your applications, allowing flexible interaction between different parts of the system. With Kawkab, creating and managing events has become easy and flexible, helping you build powerful and more interactive applications.
55 |
--------------------------------------------------------------------------------
/pages/en/basics/repositories.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Managing Repositories in Kawkab Framework
3 | description: A guide to creating and using Repositories in the Kawkab framework to organize database interactions.
4 | ---
5 |
6 | # Managing Repositories in Kawkab Framework
7 |
8 | Repositories are a fundamental component in the **Kawkab Framework** used to separate data access logic from Services and the rest of the application. This approach allows you to organize database-related operations and make the code cleaner and more reusable.
9 |
10 | ---
11 |
12 | ## Repository Creation Command
13 |
14 | To create a new repository, use the following command:
15 |
16 | ```bash
17 | npm run kawkab repository:make [module]
18 | ```
19 |
20 | ### **Parameters:**
21 | - ``: The name of the repository to create (e.g., `user`).
22 | - `[module]` _(optional)_: The name of the module the repository belongs to. If no module is specified, it will be placed in the default `main` module.
23 |
24 | ### **Example:**
25 | ```bash
26 | npm run kawkab repository:make user
27 | ```
28 |
29 | ---
30 |
31 | ## Basic Repository File Structure
32 |
33 | When creating a new repository, a file will be created containing the following structure:
34 |
35 | ```typescript
36 | import { BaseRepository, Inject, inherit } from "kawkab";
37 | import { User } from "../models/user";
38 |
39 | export class UserRepository extends inherit(BaseRepository, Inject) {
40 | findById(id: number) {
41 | return User.query().find(id);
42 | }
43 | }
44 | ```
45 |
46 | ### **Code Explanation:**
47 | 1. **BaseRepository**: The base class containing default functions for working with databases.
48 | 2. **Inject**: Used for managing dependencies (Dependency Injection).
49 | 3. **inherit**: Used to merge functionality from base classes.
50 | 4. **`findById`**: An example of a custom method to find a user based on their ID.
51 |
52 | ---
53 |
54 | ## Using Repository Inside a Service
55 |
56 | After creating the repository, it can be imported and used within Services. Here's an example:
57 |
58 | ```typescript
59 | import { BaseService, Inject, inherit } from "kawkab";
60 | import { UserRepository } from "../repositories/user";
61 |
62 | export class UserService extends inherit(BaseService, Inject) {
63 | constructor(private userRepository = UserRepository.inject()) {
64 | super();
65 | }
66 |
67 | findById(id: number) {
68 | return this.userRepository.findById(id);
69 | }
70 | }
71 | ```
72 |
73 | ### **Code Explanation:**
74 | 1. **`UserRepository.inject()`**: The repository is automatically injected for use within the service.
75 | 2. **`findById`**: A service that calls the `findById` function in the repository to execute database logic.
76 |
77 | ---
78 |
79 | ## Benefits of Using Repositories
80 |
81 | 1. **Database Logic Separation**: Makes it easier to separate data access logic from the rest of the application.
82 | 2. **Code Reusability**: Repositories can be used across multiple services.
83 | 3. **Easier Testing**: Repositories make code testing easier thanks to the separation of data logic.
84 | 4. **Code Organization**: Makes the code more organized and scalable.
85 |
86 | ---
87 |
88 | ## Conclusion
89 |
90 | Using Repositories in **Kawkab Framework**, you can better manage database logic and achieve a more organized structure for your application.
91 |
92 | 🎉 **Start creating amazing repositories in Kawkab Framework now!**
93 |
--------------------------------------------------------------------------------
/pages/en/basics/resources.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Managing Resources in Kawkab Framework
3 | description: A guide to creating and using Resources to format response data in the Kawkab framework.
4 | ---
5 |
6 | # Managing Resources in Kawkab Framework
7 |
8 | Resources are an additional layer in the **Kawkab Framework** used to format data sent to the client. Resources help standardize response formatting and make code more organized and maintainable.
9 |
10 | ---
11 |
12 | ## Resource Creation Command
13 |
14 | To create a new resource, use the following command:
15 |
16 | ```bash
17 | npm run kawkab resource:make [module]
18 | ```
19 |
20 | ### **Parameters:**
21 | - ``: The name of the resource to create (e.g., `user`).
22 | - `[module]` _(optional)_: The name of the module the resource belongs to. If no module is specified, it will be placed in the default `main` module.
23 |
24 | ### **Example:**
25 | ```bash
26 | npm run kawkab resource:make user
27 | ```
28 |
29 | ### **Output:**
30 | ```plaintext
31 | 🆗 Resource user created successfully in module main.
32 | 1️⃣ Your resource is ready! You can now import it like this:
33 |
34 | 👉 import { UserResource } from '../resources/user'
35 |
36 | 2️⃣ Use the resource like so:
37 | 👉 const users = await Users.query().get();
38 | 👉 return { status: true, users: UserResource.collect(users) };
39 | ```
40 |
41 | ---
42 |
43 | ## Basic Resource File Structure
44 |
45 | When creating a new resource, a file will be created containing the following structure:
46 |
47 | ```typescript
48 | import { BaseResource } from "kawkab";
49 |
50 | export class UserResource extends BaseResource {
51 | public resource() {
52 | return {
53 | id: this.data.id,
54 | name: this.data.name
55 | };
56 | }
57 | }
58 | ```
59 |
60 | ### **Code Explanation:**
61 | 1. **BaseResource**: The base class used for data formatting.
62 | 2. **`resource`**: A function used to define the format of data sent to the client.
63 | 3. **`this.data`**: Represents the data passed to the resource.
64 |
65 | ---
66 |
67 | ## Using Resources
68 |
69 | Resources can be used to format data before returning it to the client. Here's an example:
70 |
71 | ```typescript
72 | import { BaseController, inherit } from "kawkab";
73 | import { UserResource } from "../resources/user";
74 |
75 | export default class extends inherit(BaseController) {
76 | async get() {
77 | const users = await Users.query().get();
78 | return {
79 | status: true,
80 | users: UserResource.collect(users)
81 | };
82 | }
83 | }
84 | ```
85 |
86 | ### **Code Explanation:**
87 | 1. **`UserResource.collect(users)`**: Formats a collection of items using the resource.
88 | 2. **`users`**: Represents data retrieved from the database.
89 | 3. **`return`**: Returns the response formatted using the resource.
90 |
91 | ---
92 |
93 | ## Benefits of Using Resources
94 |
95 | 1. **Data Formatting**: Makes responses uniform and easy to understand.
96 | 2. **Code Reusability**: Resources can be used to format data across multiple modules.
97 | 3. **Security Enhancement**: Allows you to control what data is sent to the client.
98 | 4. **Code Organization**: Separates data processing logic from presentation logic.
99 |
100 | ---
101 |
102 | ## Conclusion
103 |
104 | Resources in **Kawkab Framework** help you improve the development experience of organized and maintainable APIs.
105 |
106 | 🎉 **Start organizing your responses with Resources in Kawkab Framework now!**
107 |
--------------------------------------------------------------------------------
/pages/en/basics/service.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Managing Services in Kawkab Framework
3 | description: A guide to creating and using Services in the Kawkab framework to organize and reuse business logic.
4 | ---
5 |
6 | # Managing Services in Kawkab Framework
7 |
8 | Services are components in the **Kawkab Framework** used to organize your application's core logic in a reusable way. Services allow you to group common functions and easily reuse them within Controllers or other components.
9 |
10 | ---
11 |
12 | ## Service Creation Command
13 |
14 | To create a new service, you can use the following command:
15 |
16 | ```bash
17 | npm run kawkab service:make [module]
18 | ```
19 |
20 | ### **Parameters:**
21 | - ``: The name of the service to create (e.g., `login`).
22 | - `[module]` _(optional)_: The name of the module the service belongs to. If no module is specified, it will be placed in the default `main` module.
23 |
24 | ### **Example:**
25 | ```bash
26 | npm run kawkab service:make login
27 | ```
28 |
29 | ---
30 |
31 | ## Basic Service File Structure
32 |
33 | When creating a new service, a file will be created containing the following structure:
34 |
35 | ```typescript
36 | import { BaseService, Inject, inherit } from "kawkab";
37 |
38 | export class LoginService extends inherit(BaseService, Inject) {
39 | login() {
40 | console.log("Login Service!");
41 | }
42 | }
43 | ```
44 |
45 | ### **Code Explanation:**
46 | 1. **BaseService**: A base class that provides default functionality that services can utilize.
47 | 2. **Inject**: Used for managing dependencies (Dependency Injection).
48 | 3. **inherit**: Used to merge functionality from base classes.
49 | 4. **LoginService**: An example service containing a simple `login` method that prints a message to the console.
50 |
51 | ---
52 |
53 | ## Using Service Inside a Controller
54 |
55 | After creating the service, it can be imported and used in Controllers. Here's an example of how to do this:
56 |
57 | ```typescript
58 | import { BaseController, inherit } from "kawkab";
59 | import { LoginService } from "../services/login";
60 |
61 | export default class extends inherit(BaseController) {
62 | constructor(private loginService = LoginService.inject()) {
63 | super();
64 | }
65 |
66 | async post() {
67 | this.loginService.login();
68 |
69 | return {
70 | status: true,
71 | message: "Login Successful",
72 | }
73 | }
74 | }
75 | ```
76 |
77 | ### **Code Explanation:**
78 | 1. **`LoginService.inject()`**: The service is automatically injected for use within the controller.
79 | 3. **`post`**: Uses the `login` method from the service and executes the login logic.
80 |
81 | ---
82 |
83 | ## Benefits of Using Services
84 |
85 | 1. **Code Reusability**: You can use services across multiple modules without duplicating logic.
86 | 2. **Separation of Concerns**: Services separate core business logic from controllers.
87 | 3. **Maintenance Flexibility**: Services can be updated independently without affecting the rest of the application.
88 | 4. **Dependency Management**: Kawkab Framework supports easy dependency management using `Inject`.
89 |
90 | ---
91 |
92 | ## Conclusion
93 |
94 | Using **Kawkab Framework**, managing services and organizing code becomes easier and more efficient. Services provide a powerful way to manage business logic, making your application more organized and maintainable.
95 |
96 | 🎉 **Start building amazing services in Kawkab Framework now!**
97 |
--------------------------------------------------------------------------------
/pages/en/concepts/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'application-lifecycle': {
3 | title: 'Application Lifecycle',
4 | },
5 | 'multiple-inheritance': {
6 | title: 'Multiple Inheritance',
7 | },
8 | 'dependency-injection': {
9 | title: 'Dependency Injection',
10 | },
11 | }
12 |
--------------------------------------------------------------------------------
/pages/en/concepts/application-lifecycle.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Application Lifecycle in Kawkab
3 | description: A comprehensive guide to understanding the application lifecycle in the Kawkab framework and how to initialize and manage it.
4 | ---
5 |
6 | # **Application Lifecycle in Kawkab**
7 |
8 | The **Kawkab** framework relies on the concept of **Application Lifecycle** to manage application initialization and request handling in an organized manner. The application lifecycle begins from the initialization point and moves through handling each request.
9 |
10 | ---
11 |
12 | ## **Application Initialization**
13 |
14 | ### **1. Entry Point: `index.ts`**
15 | The `index.ts` file is the entry point for a **Kawkab** application. It imports the framework and initializes the application based on predefined settings.
16 |
17 | ```ts
18 | import { kawkab } from 'kawkab'
19 | import { app as config } from './app/configuration'
20 |
21 | // Initialize the application using settings
22 | export const app = kawkab.init(config)
23 | ```
24 |
25 | ### **2. Configuration File: `configuration.ts`**
26 | This file contains the necessary settings for running the application. The application relies on a **Provider** that is responsible for registering and initializing modules.
27 |
28 | ```ts
29 | import { Provider } from './provider'
30 |
31 | export const app = {
32 | provider: Provider,
33 | }
34 | ```
35 |
36 | ---
37 |
38 | ## **Service Provider**
39 |
40 | ### **Provider's Role**
41 | The provider is responsible for registering the necessary **Modules** for the application and providing the required initialization. It is implemented through a class that inherits from `BaseProvider`.
42 |
43 | ```ts
44 | import { BaseProvider } from "kawkab"
45 |
46 | export class Provider extends BaseProvider {
47 | /**
48 | * Current provider path
49 | * Used to get the current directory path.
50 | */
51 | protected currentDir: string = __dirname
52 |
53 | /**
54 | * Register modules
55 | * This function is called once when the application starts.
56 | * Registers and initializes modules needed for the application.
57 | */
58 | async register() {
59 | await this.modules()
60 | }
61 |
62 | /**
63 | * Setup with each request
64 | * This function is called with each new request.
65 | * Used to register additional settings or services.
66 | */
67 | boot() {
68 | // Write code here
69 | }
70 | }
71 | ```
72 |
73 | ### **Provider Lifecycle**
74 | 1. **Register**:
75 | Called only once when the server starts. Used to register modules and perform necessary initializations.
76 |
77 | 2. **Boot**:
78 | Called with each new request to handle dynamic settings or request services.
79 |
80 | ---
81 |
82 | ## **Application Lifecycle Explanation**
83 |
84 | 1. **Framework Initialization:**
85 | - The framework starts when `kawkab.init()` is called in `index.ts`.
86 | - Application settings are imported from `configuration.ts`.
87 |
88 | 2. **Module Registration:**
89 | - The provider calls `register()` to register modules needed for the application.
90 |
91 | 3. **Request Handling:**
92 | - `boot()` is called with each new request to provide additional services or reinitialize.
93 |
94 | ---
95 |
96 | ## **Summary**
97 |
98 | The **Kawkab** framework provides a clear and organized application lifecycle, allowing developers to manage module registration and initialization seamlessly. Using the `Provider`, initialization can be customized and high application performance can be ensured when handling requests.
99 |
--------------------------------------------------------------------------------
/pages/en/database/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | "configuration": {
3 | title: "Configurations",
4 | },
5 | "query-builder": {
6 | title: "Query Builder",
7 | },
8 | "models": {
9 | title: "Models",
10 | },
11 | "relationships": {
12 | title: "Relationships",
13 | },
14 | "pagination": {
15 | title: "Pagination",
16 | },
17 | "mutators-casting": {
18 | title: "Mutators",
19 | },
20 | "hooks": {
21 | title: "Hooks",
22 | },
23 | "transactions": {
24 | title: "Transactions",
25 | },
26 | "serialization": {
27 | title: "Serialization",
28 | },
29 | };
30 |
--------------------------------------------------------------------------------
/pages/en/database/configuration.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Database Configuration
3 | description: A comprehensive guide to setting up and configuring supported databases in the Kawkab framework.
4 | ---
5 |
6 | # Database Configuration
7 |
8 | ## Overview
9 |
10 | Kawkab supports many popular database management systems. You can configure database settings through the `.env` file in the main project folder.
11 |
12 | ## Supported Databases
13 |
14 | ### MySQL
15 | The most popular relational database system, ideal for small to medium-sized applications.
16 |
17 | ```env
18 | DATABASE_CLIENT=mysql
19 | DATABASE_HOST=127.0.0.1
20 | DATABASE_PORT=3306
21 | DATABASE_USER=root
22 | DATABASE_PASSWORD=your_password
23 | DATABASE_NAME=your_database
24 | ```
25 |
26 | #### MySQL Features
27 | - Easy to use and set up
28 | - Good read performance
29 | - Extensive community support
30 | - Suitable for traditional web applications
31 |
32 | ### PostgreSQL
33 | An advanced database system with additional features, perfect for complex applications.
34 |
35 | ```env
36 | DATABASE_CLIENT=pgsql
37 | DATABASE_HOST=127.0.0.1
38 | DATABASE_PORT=5432
39 | DATABASE_USER=postgres
40 | DATABASE_PASSWORD=your_password
41 | DATABASE_NAME=your_database
42 | ```
43 |
44 | #### PostgreSQL Features
45 | - Support for advanced data types
46 | - Advanced text search capabilities
47 | - Better handling of concurrency
48 | - Suitable for enterprise-level applications
49 |
50 | ### SQLite
51 | A lightweight database that operates as a single file, ideal for development and small applications.
52 |
53 | ```env
54 | DATABASE_CLIENT=sqlite
55 | DATABASE_NAME=database/database.sqlite
56 | ```
57 |
58 | #### SQLite Features
59 | - No need for a separate server
60 | - Easy to transfer and back up
61 | - Ideal for development and testing
62 | - Suitable for mobile applications
63 |
64 | ## Connection Settings
65 |
66 | ### Basic Settings
67 |
68 | ```env
69 | # Database type
70 | DATABASE_CLIENT=mysql
71 |
72 | # Connection details
73 | DATABASE_HOST=127.0.0.1
74 | DATABASE_PORT=3306
75 | DATABASE_USER=root
76 | DATABASE_PASSWORD=your_password
77 | DATABASE_NAME=your_database
78 | ```
79 |
80 | ### Settings Explanation
81 |
82 | | Setting | Description | Possible Values |
83 | |---------------------|-----------------------------|-------------------------|
84 | | `DATABASE_CLIENT` | Database type | `mysql`, `pgsql`, `sqlite` |
85 | | `DATABASE_HOST` | Server address | IP or domain name |
86 | | `DATABASE_PORT` | Connection port | Port number |
87 | | `DATABASE_USER` | Username | String |
88 | | `DATABASE_PASSWORD` | Password | String |
89 | | `DATABASE_NAME` | Database name | String |
90 |
91 | ## Best Practices
92 |
93 | ### 1. Security
94 | - Do not store passwords in version control
95 | - Use a database user with limited privileges
96 | - Encrypt connections in the production environment
97 |
98 | ### 2. Performance
99 | - Adjust the connection pool size based on your app's needs
100 | - Use indexes appropriately
101 | - Monitor query performance
102 |
103 | ### 3. Backups
104 | - Set up regular backups
105 | - Test backup restoration
106 | - Keep backups in different locations
107 |
108 | ## Common Issues and Solutions
109 |
110 | ### Connection Issue
111 | ```bash
112 | # Ensure the database server is running
113 | sudo service mysql status
114 |
115 | # Verify connection details
116 | mysql -u root -p
117 | ```
118 |
119 | ### Permission Issue
120 | ```sql
121 | -- Grant privileges to the user
122 | GRANT ALL PRIVILEGES ON database_name.* TO 'user'@'localhost';
123 | FLUSH PRIVILEGES;
124 | ```
125 |
126 | ## Conclusion
127 |
128 | Database setup in Kawkab:
129 | - Flexible and supports multiple systems
130 | - Easy to configure via the `.env` file
131 | - Customizable based on project needs
132 |
133 | Final Tips:
134 | - Choose the right database type for your project
135 | - Follow security best practices
136 | - Document your database settings
137 | - Keep regular backups
--------------------------------------------------------------------------------
/pages/en/database/hooks.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Hooks
3 | description: A comprehensive guide to hooks in the Kawkab framework, explaining lifecycle events and how to use them in your models.
4 | ---
5 |
6 | # Hooks
7 |
8 | Kawkab models trigger several events, allowing you to hook into the following moments in the model's lifecycle: `creating`, `created`, `updating`, `updated`, `saving`, `saved`, `deleting`, `deleted`, `restoring`, `restored`, `trashed`, `forceDeleting`, and `forceDeleted`.
9 |
10 | Events ending with `-ing` are fired before any changes are saved to the model, while events ending with `-ed` are fired after the changes are saved.
11 |
12 | ## Available Hooks
13 |
14 | | Hook | Description |
15 | |----------------------------------|----------------------------------------------------------------------------------------------|
16 | | `creating`, `created` | When a new model is saved for the first time |
17 | | `updating`, `updated` | When an existing model is modified and the `save` method is called |
18 | | `saving`, `saved` | When a model is being created or updated - even if no changes have occurred in the model |
19 | | `deleting`, `deleted` | When a model is being deleted, including soft deletes |
20 | | `restoring`, `restored` | When a model is restored (after a soft delete) |
21 | | `trashed` | When a model is soft deleted |
22 | | `forceDeleting`, `forceDeleted` | When a model is permanently deleted |
23 |
24 | :::tip
25 | When executing a bulk update or delete query via Kawkab, the `saved`, `updated`, `deleting`, and `deleted` events will not be triggered for the affected models. This is because the models are not actually retrieved during bulk updates or deletes.
26 | :::
27 |
28 | ## Declaring Hooks
29 |
30 | Currently, there are two ways to add hooks programmatically:
31 |
32 | ```js
33 | class User extends Model {}
34 |
35 | User.creating(user => {
36 | // logic to run before creating
37 | });
38 | ```
39 |
40 | ```js
41 | class User {
42 | static booted() {
43 | this.creating(user => {
44 | // logic to run before creating
45 | });
46 |
47 | this.created(user => {
48 | // logic to run after created
49 | });
50 | }
51 | }
52 | ```
53 |
54 | ## Hooks and Transactions
55 |
56 | ```js
57 | User.deleted(async (user, { client }) => {
58 | const query = user.related('posts');
59 |
60 | if (client) {
61 | query.transacting(client);
62 | }
63 |
64 | await query.delete();
65 | });
66 |
67 | const trx = await Kawkab.beginTransaction();
68 |
69 | await user.delete({
70 | client: trx
71 | });
72 |
73 | await trx.commit();
74 | ```
75 |
76 | In the example above, we handle related model deletions within the transaction, ensuring consistency and atomicity when deleting a user and their related posts.
--------------------------------------------------------------------------------
/pages/en/database/pagination.mdx:
--------------------------------------------------------------------------------
1 | # Pagination
2 |
3 | Kawkab has built-in support for pagination. You can paginate query results by chaining the `paginate` method.
4 |
5 | The `paginate` method takes the page number as the first argument and the number of rows to fetch as the second argument. Internally, we execute an additional query to calculate the total number of rows.
6 |
7 | ### Basic Usage
8 |
9 | ```js
10 | const users = await db.table('users')
11 | .where('vote', '>', 1)
12 | .paginate(2, 15); // instanceof Paginator
13 |
14 | const users = await User.query()
15 | .where('vote', '>', 1)
16 | .paginate(1, 15); // instanceof Paginator
17 |
18 | const users = await db.table('users')
19 | .where('vote', '>', 1)
20 | .forPage(2, 15)
21 | .get(); // instanceof Array
22 |
23 | const users = await User.query()
24 | .where('vote', '>', 1)
25 | .forPage(1, 15)
26 | .get(); // instanceof Collection
27 |
28 | users.map(user => {
29 | //
30 | });
31 | ```
32 |
33 | If not specified, the number of rows per page defaults to 15. If you are using models, you can also set the `perPage` attribute as the default number of rows per page for each model.
34 |
35 | ```js
36 | class Post extends Model {}
37 | class User extends Model {
38 | perPage = 20;
39 | }
40 |
41 | const posts = await Post.query().paginate();
42 | console.log(posts.perPage()); // 15
43 |
44 | const users = await User.query().paginate();
45 | console.log(users.perPage()); // 20
46 | ```
47 |
48 | The `paginate` method returns an instance of `Paginator`. It contains pagination metadata along with the rows that were fetched.
49 |
50 | Each instance of `Paginator` provides additional pagination information via the following methods:
51 |
52 | | Method | Description |
53 | | -------------------------- | ---------------------------------------------------------- |
54 | | `paginator.count()` | Get the number of items for the current page. |
55 | | `paginator.currentPage()` | Get the current page number. |
56 | | `paginator.hasMorePages()` | Check if there are more items in the data store. |
57 | | `paginator.items()` | Get the items for the current page. |
58 | | `paginator.lastPage()` | Get the last available page number. |
59 | | `paginator.perPage()` | The number of items to display per page. |
60 | | `paginator.total()` | Get the total number of matching items in the data store. |
61 |
62 | ### Conversions to Object/JSON
63 |
64 | You can also serialize the paginated results to an object/JSON by calling the `toData` or `toJson` method. By default, it returns the keys in snake_case format. However, you can pass a naming strategy to override the default convention.
65 |
66 | ```JSON
67 | {
68 | "total": 45,
69 | "per_page": 15,
70 | "current_page": 1,
71 | "last_page": 3,
72 | "count": 15,
73 | "data": [
74 | {
75 | // Record...
76 | },
77 | {
78 | // Record...
79 | }
80 | ]
81 | }
82 | ```
83 |
84 | The paginator will automatically convert it to JSON when serialized to a string, so it can be used directly in your application's route or controller. Your express/Koa application will automatically serialize JSON:
85 |
86 | ```js
87 | const users = await User.query().paginate(req.query.page || 1);
88 |
89 | return res.ok({
90 | "status": true,
91 | "users": users
92 | });
93 | ```
--------------------------------------------------------------------------------
/pages/en/database/transactions.mdx:
--------------------------------------------------------------------------------
1 | # Handling Transactions (Transactions)
2 |
3 | You can use the `transaction` method available in the Sutando connection to execute a set of operations within a database transaction. If an exception occurs within the transaction's closure, the transaction will automatically be rolled back and the exception will be rethrown. If the closure is executed successfully, the transaction will be automatically committed. There is no need to worry about manually rolling back or committing when using the `transaction` method:
4 |
5 | ```js
6 | import { db } from "kawkab";
7 |
8 | await db.transaction(async (trx) => {
9 | await User.query().transacting(trx).create(/* ... */);
10 |
11 | await db.table('users').transacting(trx).insert(/* ... */);
12 |
13 | const user = new User;
14 | user.name = 'Sally';
15 |
16 | await user.save({
17 | client: trx,
18 | });
19 | });
20 | ```
21 |
22 | #### Using Transactions Manually
23 |
24 | If you want to start a transaction manually and have full control over rolling back and committing, you can use the `beginTransaction` method available through `sutando`:
25 |
26 | ```js
27 | import { db } from "kawkab";
28 |
29 | const trx = await db.beginTransaction();
30 | ```
31 |
32 | You can roll back the transaction using the `rollback` method:
33 |
34 | ```js
35 | await trx.rollback();
36 | ```
37 |
38 | Finally, you can commit the transaction using the `commit` method:
39 |
40 | ```js
41 | await trx.commit();
42 | ```
43 |
44 | Here is a complete example:
45 |
46 | ```js
47 | import { db } from "kawkab";
48 |
49 | const trx = await db.beginTransaction();
50 |
51 | try {
52 | const user = new User;
53 | user.name = 'Sally';
54 |
55 | await user.save({
56 | client: trx,
57 | });
58 |
59 | await trx.commit();
60 | } catch (e) {
61 | await trx.rollback();
62 |
63 | console.log(e.stack);
64 | }
65 | ```
--------------------------------------------------------------------------------
/pages/en/digging-deeper/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | localization: {
3 | title: "Localization",
4 | },
5 | dto: {
6 | title: "Data Transfer Object",
7 | },
8 | enums: {
9 | title: "Enums",
10 | },
11 | actions: {
12 | title: "Actions",
13 | },
14 | collections: {
15 | title: "Collections",
16 | },
17 | caching: {
18 | title: "Caching",
19 | },
20 | http: {
21 | title: "HTTP Requests",
22 | },
23 | time: {
24 | title: "Time",
25 | },
26 | files: {
27 | title: "Files",
28 | },
29 | folders: {
30 | title: "Folders",
31 | },
32 | strategies: {
33 | title: "Strategies",
34 | },
35 | settings: {
36 | title: "Settings",
37 | },
38 | strings: {
39 | title: "Strings",
40 | },
41 | numbers: {
42 | title: "Numbers",
43 | },
44 | data: {
45 | title: "Data",
46 | },
47 | logger: {
48 | title: "Logger",
49 | },
50 | notifications: {
51 | title: "Notifications",
52 | },
53 | commands: {
54 | title: "Commands",
55 | },
56 | faker: {
57 | title: "Faker Data",
58 | },
59 | factories: {
60 | title: "Factories",
61 | },
62 | test: {
63 | title: "Tests",
64 | },
65 | 'test-driven-development': {
66 | title: 'Test-Driven Development',
67 | },
68 | queue: {
69 | title: "Queues",
70 | },
71 | jobs: {
72 | title: "Jobs",
73 | },
74 | 'cron-jobs': {
75 | title: "Cron Jobs",
76 | },
77 | "api-documentation": {
78 | title: "API Documentation",
79 | },
80 | };
81 |
--------------------------------------------------------------------------------
/pages/en/digging-deeper/actions.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Actions in Kawkab
3 | description: A comprehensive guide to creating and using actions in your application with the command `npm run kawkab action:make`.
4 | ---
5 |
6 | # Creating Actions in Kawkab
7 |
8 | Actions are classes that represent activities or operations that can be performed in your application, such as updating a password, generating random numbers, and more. With **Kawkab**, you can easily create actions and organize the related code in a flexible manner to perform a specific task.
9 |
10 | ## Creating a New Action with Kawkab
11 |
12 | To create a new **Action** with **Kawkab**, run the following command in the terminal:
13 |
14 | ```bash
15 | npm run kawkab action:make [module]
16 | ```
17 |
18 | ### **Parameter Details:**
19 |
20 | - **``**: The name of the action you want to create (e.g., `UpdateUserPassword`).
21 | - **`[module]`**: The name of the module containing the action (optional, default is `main`).
22 |
23 | ### Example of running the command:
24 |
25 | ```bash
26 | npm run kawkab action:make UpdateUserPassword
27 | ```
28 |
29 | After running the command, an **Action** named `UpdateUserPassword` will be created in the `main` module.
30 |
31 | ### What happens after running the command?
32 |
33 | - A file for the **Action** named `'UpdateUserPassword'` will be created successfully.
34 | - You can now use this **Action** in your application by importing and using it as shown in the following example.
35 |
36 | ## Using an Action in the Application
37 |
38 | Once the **Action** is created, you can import and use it anywhere in your application.
39 |
40 | ### Importing the Action:
41 |
42 | To import the **Action** that was created, use the following code in your file:
43 |
44 | ```javascript
45 | import { UpdateUserPasswordAction } from "../actions/UpdateUserPassword";
46 | ```
47 |
48 | ### Content of the Action File:
49 |
50 | The **Action** file `UpdateUserPassword` will contain the following code:
51 |
52 | ```javascript
53 | import { BaseAction } from "kawkab";
54 |
55 | export class UpdateUserPasswordAction extends BaseAction {
56 | handle() {
57 | // Add the code for handling password update here
58 | }
59 | }
60 | ```
61 |
62 | ### Using the Action in the Application:
63 |
64 | You can now use the **Action** by creating a new object from the `UpdateUserPasswordAction` class as follows:
65 |
66 | ```javascript
67 | const action = new UpdateUserPasswordAction();
68 | action.handle(); // The code inside the handle function will be executed
69 | ```
70 |
71 | #### Passing Data to the Action:
72 |
73 | You can pass data when creating the **Action** object:
74 |
75 | ```javascript
76 | const action = new UpdateUserPasswordAction({ id: 1, name: 'Hassan' });
77 | console.log(action.data); // Will print { id: 1, name: 'Hassan' }
78 | ```
79 |
80 | #### Accessing Data Inside the Action:
81 |
82 | Inside the **Action**, you can access the passed data using `this.data`:
83 |
84 | ```javascript
85 | export class UpdateUserPasswordAction extends BaseAction {
86 | handle() {
87 | console.log(this.data); // Will print the passed data like { id: 1, name: 'Hassan' }
88 | }
89 | }
90 | ```
91 |
92 | ## Additional Notes
93 |
94 | - **Multiple Actions:** You can create multiple actions in your application using the same approach, creating new `Action` classes for any operation you need.
95 | - **Expanding Functionality:** Inside each `Action`, you can add your custom business logic, such as database queries or handling the passed data.
96 | - **Data Flexibility:** Data can be passed when creating the **Action** for easy access within the **Action** using `this.data`.
97 |
98 | ## Conclusion
99 |
100 | **Actions** in Kawkab provide a powerful way to organize operations that your application needs to perform. With **Kawkab**, you can easily create and use actions to perform tasks like updating data, sending notifications, and much more. Leverage the flexibility that Kawkab offers to structure your application and improve its efficiency!
--------------------------------------------------------------------------------
/pages/en/digging-deeper/commands.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Command System in Kawkab
3 | description: A comprehensive guide to using and creating commands in the Kawkab framework.
4 | ---
5 |
6 | # Command System in Kawkab
7 |
8 | The **command** system in the **Kawkab** framework provides a powerful and flexible command-line interface to manage and execute various tasks in your application. You can use the built-in commands or create custom ones.
9 |
10 | ## Viewing Available Commands
11 |
12 | To get a list of all available commands, run:
13 |
14 | ```bash
15 | npm run kawkab
16 | ```
17 |
18 | This command will display a list of all available commands with a brief description of each one.
19 |
20 | ## Creating a New Command
21 |
22 | ### Basic Syntax
23 |
24 | ```bash
25 | npm run kawkab command:make [module]
26 | ```
27 |
28 | ### Parameter Details:
29 |
30 | - **``**: The name of the command you wish to create.
31 | - **`[module]`**: The name of the module that will contain the command (optional, the default is `main`).
32 |
33 | ### Example:
34 |
35 | ```bash
36 | npm run kawkab command:make hello
37 | ```
38 |
39 | This command will create a new command file at the appropriate location with the following basic structure:
40 |
41 | ```typescript
42 | import { Command } from "kawkab";
43 |
44 | export default function(program: Command): void {
45 | program
46 | // Command syntax: '' is required, '[variable_name]' is optional
47 | .command("hello [module]")
48 | // Description of the command that will appear in the CLI help
49 | .description("Your custom command description")
50 | // Action to be executed when the command is run
51 | .action(async (name: string, module: string = "main") => {
52 | // Write your command logic here
53 | console.log(`Hello ${name}`);
54 | });
55 | }
56 | ```
57 |
58 | ## Command Structure
59 |
60 | ### Core Components
61 |
62 | 1. **`command()`**: Defines the name and syntax of the command
63 | - Required variables are written between `<>`
64 | - Optional variables are written between `[]`
65 |
66 | 2. **`description()`**: A brief description of the command that appears in the help list
67 |
68 | 3. **`action()`**: The function containing the logic for executing the command
69 | - It receives the variables defined in the command syntax
70 | - It can be asynchronous (`async`)
71 |
72 | ### Adding Options
73 |
74 | You can add options to your command using `option()`:
75 |
76 | ```typescript
77 | program
78 | .command("hello ")
79 | .option("-c, --capitalize", "Convert the name to uppercase")
80 | .action(async (name: string, options) => {
81 | const output = options.capitalize ? name.toUpperCase() : name;
82 | console.log(`Hello ${output}`);
83 | });
84 | ```
85 |
86 | ## Best Practices
87 |
88 | 1. **Clear Names**: Use descriptive and clear names for your commands.
89 | 2. **Good Documentation**: Write a clear and detailed description for each command and its options.
90 | 3. **Input Validation**: Always validate inputs before executing the command.
91 | 4. **Clear Messages**: Display clear messages to the user about the result of the command execution.
92 | 5. **Error Handling**: Implement proper error handling for potential issues.
93 |
94 | ## Conclusion
95 |
96 | The command system in Kawkab provides an easy and flexible way to add new functionality to your application through the command-line interface. With support for required and optional variables and custom options, you can create powerful and useful commands for your application.
--------------------------------------------------------------------------------
/pages/en/digging-deeper/data.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Creating Data Files with Kawkab
3 | ---
4 |
5 | # Data Files in Kawkab
6 |
7 | Data files in **Kawkab** are used to organize and store static or dependent data that is utilized in your application. This data could be lists, settings, or any other fixed information you wish to use in your project in an organized manner.
8 |
9 | ## Creating Data Files with Kawkab
10 |
11 | In this guide, we will show you how to create new data files using the **Kawkab** framework and integrate them into your application.
12 |
13 | ## Step 1: Creating a New Data File
14 |
15 | To create a new data file using **Kawkab**, run the following command in the terminal:
16 |
17 | ```bash
18 | npm run kawkab data:make [module]
19 | ```
20 |
21 | ### **Parameter Details:**
22 |
23 | - **``**: The name of the data file you want to create (e.g., `cats`).
24 | - **`[module]`**: The name of the module that contains the data (optional, default is `main`).
25 |
26 | ### Example of Command Execution:
27 |
28 | ```bash
29 | npm run kawkab data:make cats
30 | ```
31 |
32 | This command will create a data file named `cats` inside the `main` module.
33 |
34 | ### What Happens After Running the Command?
35 |
36 | - A data file named `'cats'` will be created in the specified module.
37 | - This file will contain data that can be used in your application. For example, this guide will create a file containing a list of popular cat breeds.
38 |
39 | ## Step 2: Using the Data in Your Application
40 |
41 | Once the data file is created, you can import and use it within your project files.
42 |
43 | ### Importing the Data:
44 |
45 | To import the data that has been created, use the following code in your file:
46 |
47 | ```javascript
48 | import catsData from '../data/cats';
49 | ```
50 |
51 | ### Contents of the Data File:
52 |
53 | The `cats` data file will contain the following data (cat breeds):
54 |
55 | ```javascript
56 | export default {
57 | data: [
58 | "Persian", // Persian Cats
59 | "Maine Coon", // Maine Coon Cats
60 | "Bengal", // Bengal Cats
61 | "Siamese", // Siamese Cats
62 | "Ragdoll", // Ragdoll Cats
63 | "British Shorthair", // British Shorthair Cats
64 | "Sphynx", // Sphynx Cats
65 | "Abyssinian", // Abyssinian Cats
66 | "Scottish Fold", // Scottish Fold Cats
67 | "Birman" // Birman Cats
68 | ]
69 | }
70 | ```
71 |
72 | ### Using the Data in Your Application:
73 |
74 | Now, you can access and use the data easily anywhere in your application:
75 |
76 | ```javascript
77 | const data = catsData.data;
78 | console.log(data); // Will print the list of cat breeds
79 | ```
80 |
81 | ## Additional Notes
82 |
83 | - Ensure that the path you use to import the data is correct according to your project’s folder structure.
84 | - You can use the same approach to create other data files by changing the name of the created file (e.g., `dogs` instead of `cats`).
85 |
86 | - If you are using multiple modules, you can specify the module that contains the data using the `[module]` parameter:
87 |
88 | ```bash
89 | npm run kawkab data:make cats customModuleName
90 | ```
91 |
92 | ## Conclusion
93 |
94 | Creating data files with Kawkab helps organize and streamline the management of static data in your application. With Kawkab, you can easily create these files and integrate them into your application quickly. Enjoy using **Kawkab** to build your applications more efficiently and flexibly!
--------------------------------------------------------------------------------
/pages/en/digging-deeper/dto.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Creating Data Transfer Objects (DTOs) with Kawkab
3 | description: A comprehensive guide to creating and using Data Transfer Objects (DTOs) in your application using Kawkab.
4 | ---
5 |
6 | # Data Transfer Objects (DTOs) with Kawkab
7 |
8 | A **Data Transfer Object (DTO)** is an object used to transfer data between different layers of your application in an organized and flexible way. With **Kawkab**, you can easily create DTOs and use them to manage incoming request data or data passed between different parts of your application.
9 |
10 | ---
11 |
12 | ## Creating a New DTO with Kawkab
13 |
14 | To create a new **DTO**, run the following command:
15 |
16 | ```bash
17 | npm run kawkab dto:make [module]
18 | ```
19 |
20 | ### **Parameter Details:**
21 |
22 | - **``**: The name of the DTO you want to create (e.g., `User`).
23 | - **`[module]`**: The name of the module that contains the DTO (optional, default is `main`).
24 |
25 | ### **Practical Example:**
26 |
27 | ```bash
28 | npm run kawkab dto:make user
29 | ```
30 |
31 | ### **Result of Execution:**
32 |
33 | - A DTO object named `UserDTO` will be created in the `main` module.
34 | - You can now easily use this DTO in your application.
35 |
36 | ---
37 |
38 | ## How to Use DTO in Your Application
39 |
40 | Once the DTO object is created, you can import and use it within your project files.
41 |
42 | ### Importing the DTO:
43 |
44 | To use the DTO, import it as shown below:
45 |
46 | ```javascript
47 | import { UserDTO } from "../dto/user";
48 | ```
49 |
50 | ### Creating a DTO Object:
51 |
52 | You can create a DTO object in three ways:
53 |
54 | #### 1. **Creating the Object Without Passing Data:**
55 |
56 | When no data is passed, the DTO object will automatically fetch the data from the request:
57 |
58 | ```javascript
59 | const dto = new UserDTO();
60 | console.log(dto.data); // Contains data from the current request
61 | ```
62 |
63 | #### 2. **Passing Data Directly When Creating the Object:**
64 |
65 | You can pass data manually when creating the object:
66 |
67 | ```javascript
68 | const dto = new UserDTO({
69 | email: "hassan@example.com",
70 | });
71 | console.log(dto.data); // Contains { email: "hassan@example.com" }
72 | ```
73 |
74 | ---
75 |
76 | ## DTO File Content:
77 |
78 | The created `UserDTO` file will contain the following code:
79 |
80 | ```javascript
81 | import { BaseDTO, rule as r, req } from "kawkab";
82 |
83 | export interface Item {
84 | [key: string]: any;
85 | }
86 |
87 | export class UserDTO extends BaseDTO {
88 | constructor(data: Item = req.inputs()) {
89 | super();
90 | this.dto(this, data);
91 | }
92 |
93 | static inject(data: Item = req.inputs()) {
94 | return { ...new this(data) };
95 | }
96 |
97 | data(i: Item): object {
98 | return {
99 | email: i?.email,
100 | };
101 | }
102 |
103 | rules() {
104 | return {
105 | email: r.string().email(),
106 | };
107 | }
108 | }
109 | ```
110 |
111 | ---
112 |
113 | ## Additional Notes
114 |
115 | 1. **Data Validation:**
116 | - You can define validation rules using the `rules()` method. In the above example, a validation rule for the email field is defined.
117 |
118 | 2. **Default Data Fetching:**
119 | - If no data is passed during object creation, request data is automatically fetched using `req.inputs()`.
120 |
121 | 3. **Organizing Data:**
122 | - You can define the final structure of the data via the `data()` method.
123 |
124 | ---
125 |
126 | ## Conclusion
127 |
128 | Kawkab provides a flexible way to create Data Transfer Objects (DTOs) to organize and validate data easily. By using this approach, you can improve your application's code and separate data logic from business logic. Take advantage of this feature to build more stable and organized applications.
--------------------------------------------------------------------------------
/pages/en/digging-deeper/enums.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Creating Enums with Kawkab
3 | description: A comprehensive guide to creating and using Enums in your application using the `npm run kawkab enum:make` command.
4 | ---
5 |
6 | # Creating Enums with Kawkab
7 |
8 | **Enums** are a great way to organize predefined constant values in your application in a structured and scalable way. In this guide, we will learn how to create and use **Enums** with the **Kawkab** framework.
9 |
10 | ## Creating a New Enum with Kawkab
11 |
12 | To create a new **Enum** using **Kawkab**, run the following command in your terminal:
13 |
14 | ```bash
15 | npm run kawkab enum:make [module]
16 | ```
17 |
18 | ### **Parameter Details:**
19 |
20 | - **``**: The name of the Enum you want to create (for example, `UserType`).
21 | - **`[module]`**: The name of the module that contains the Enum (optional, the default is `main`).
22 |
23 | ### Example of Running the Command:
24 |
25 | ```bash
26 | npm run kawkab enum:make UserType
27 | ```
28 |
29 | After running the command, an Enum named `UserType` will be created in the `main` module.
30 |
31 | ### What Happens After Running the Command?
32 |
33 | - A file named `UserType` will be successfully created as an Enum.
34 | - You can now use the Enum in your application by importing and utilizing it, as shown in the following example.
35 |
36 | ## Using the Enum in Your Application
37 |
38 | Once the Enum is created, you can import and use it anywhere in your application.
39 |
40 | ### Importing the Enum:
41 |
42 | To import the Enum you created, use the following code in your file:
43 |
44 | ```javascript
45 | import { UserType, UserTypeEnum } from "../enums/UserType";
46 | ```
47 |
48 | ### Enum File Content:
49 |
50 | The content of the `UserType` Enum file will look like this:
51 |
52 | ```javascript
53 | import { BaseEnum as Enum } from "kawkab";
54 |
55 | export enum UserTypeEnum {
56 | Administrator = 0, // Administrator
57 | Moderator = 1, // Moderator
58 | Subscriber = 2, // Subscriber
59 | SuperAdministrator = 3, // Super Administrator
60 | // You can add more values here
61 | }
62 |
63 | Enum.set(UserTypeEnum);
64 |
65 | export class UserType extends Enum {}
66 | ```
67 |
68 | ### Using the Enum in the Application:
69 |
70 | You can use the Enum in multiple ways, as shown in the following examples:
71 |
72 | #### Method 1: Accessing Values Using the Enum
73 |
74 | ```javascript
75 | console.log(UserTypeEnum.Administrator); // Will print 0
76 | console.log(UserTypeEnum.Moderator); // Will print 1
77 | ```
78 |
79 | #### Method 2: Using the `get` Method to Access Values
80 |
81 | ```javascript
82 | console.log(UserType.get('Administrator')); // Will print 0
83 | console.log(UserType.get('Subscriber')); // Will print 2
84 | ```
85 |
86 | ## Additional Notes
87 |
88 | - **Using Enum with Other Classes:** You can use the Enum anywhere in the application where you need to represent constant values. These could represent user types, the state of something, etc.
89 | - **Flexibility:** New values can be easily added to the Enum at any time.
90 | - **Renaming:** If you need to rename any values in the Enum, you can modify them directly within the file.
91 |
92 | ## Conclusion
93 |
94 | Using **Enums** in Kawkab helps organize constant values in your application in a clearer and more powerful way. With **Kawkab**, you can create and use Enums in a flexible and simplified manner within your project. Enjoy building more efficient and organized applications!
--------------------------------------------------------------------------------
/pages/en/digging-deeper/factories.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Factories in Kawkab
3 | description: A comprehensive guide to creating and using factories in Kawkab with Faker for generating realistic test data.
4 | ---
5 |
6 | # Factories in Kawkab
7 |
8 | ## Overview
9 | Factories in Kawkab provide a simple and effective way to generate fake data for testing and development purposes. Factories use the Faker library to create realistic data.
10 |
11 | ## Basic Usage
12 |
13 | ### Creating a New Factory
14 |
15 | To create a new **Factory**, run the following command:
16 |
17 | ```bash
18 | npm run kawkab factory:make [module]
19 | ```
20 |
21 | ### **Parameter Details:**
22 |
23 | - **``**: The name of the factory you want to create (e.g., `User`).
24 | - **`[module]`**: The module that contains the factory (optional, default is `main`).
25 |
26 | ### **Practical Example:**
27 |
28 | ```bash
29 | npm run kawkab factory:make user
30 | ```
31 |
32 | ```typescript
33 | import { BaseFactory, faker } from 'kawkab';
34 | import { User } from "../models/user";
35 |
36 | export class UserFactory extends BaseFactory {
37 | async handle() {
38 | const data = {
39 | username: faker.internet.userName(),
40 | email: faker.internet.email()
41 | };
42 |
43 | await User.query().insert(data);
44 | }
45 | }
46 | ```
47 |
48 | ### Using the Factory
49 |
50 | ```typescript
51 | // Create 10 users
52 | new UserFactory(10);
53 |
54 | // Create a single user
55 | new UserFactory();
56 | ```
57 |
58 | ## Key Features
59 |
60 | 1. **Simplicity**: Generate data with a single line of code.
61 | 2. **Flexibility**: The generated data can be customized as needed.
62 | 3. **Automation**: Data is automatically inserted into the database.
63 | 4. **Scalability**: New factories can be added easily.
64 |
65 | ## Best Practices
66 |
67 | 1. **Organizing Factories**:
68 | - Place all factories in the `factories` folder.
69 | - Follow the naming convention `[ModelName]Factory`.
70 |
71 | 2. **Data**:
72 | - Use Faker to generate realistic data.
73 | - Avoid hardcoded data unless necessary.
74 | - Ensure all required fields are covered.
75 |
76 | 3. **Relationships**:
77 | - Create related records first.
78 | - Use other factories to create related data.
79 |
80 | 4. **Testing**:
81 | - Use factories in your test files.
82 | - Create diverse test data.
83 | - Clean up the generated data after tests.
84 |
85 | ## Important Notes
86 |
87 | 1. Factories are designed for use in development and testing environments only.
88 | 2. Do not use factories in a production environment.
89 | 3. Make sure to use a compatible version of Faker.
90 | 4. Clean up the generated data periodically.
91 |
92 | ## Conclusion
93 |
94 | Factories in Kawkab provide a simple and effective way to generate test data. You can quickly generate realistic data for your application, making development and testing faster and easier.
--------------------------------------------------------------------------------
/pages/en/digging-deeper/logger.mdx:
--------------------------------------------------------------------------------
1 | # The Logger in Kawkab Kawkab
2 |
3 | ## Introduction
4 | Logging is an essential part of any application, as it helps track the system's state and behavior. The **Kawkab Kawkab** framework provides a built-in logging system that allows you to log messages at multiple levels such as: `info`, `warn`, `error`, `verbose`, `debug`, and `silly`.
5 |
6 | ---
7 |
8 | ## Using the Logging System
9 |
10 | ### Importing
11 | To start using the logging system in **Kawkab Kawkab**, you need to import `log` from the **kawkab** library:
12 |
13 | ```ts
14 | import { log } from "kawkab";
15 | ```
16 |
17 | ---
18 |
19 | ## Logging Messages
20 |
21 | ### Logging a General Message
22 | To log a message at a specific level, use the `message` function and specify the desired log level.
23 |
24 | #### Example:
25 | ```ts
26 | log.message('info', 'This is an informational message.');
27 | ```
28 |
29 | ---
30 |
31 | ### Logging an Error Message
32 | To log an error message, use the `error` method:
33 |
34 | #### Example:
35 | ```ts
36 | log.error('An error occurred in the system.');
37 | ```
38 |
39 | ---
40 |
41 | ### Logging a Warning Message
42 | To log a warning message, use the `warn` method:
43 |
44 | #### Example:
45 | ```ts
46 | log.warn('This is a warning message.');
47 | ```
48 |
49 | ---
50 |
51 | ### Logging an Informational Message
52 | To log an informational message, use the `info` method:
53 |
54 | #### Example:
55 | ```ts
56 | log.info('This is an informational message.');
57 | ```
58 |
59 | ---
60 |
61 | ### Logging a Detailed Message
62 | To log a message with more details than an informational level, use the `verbose` method:
63 |
64 | #### Example:
65 | ```ts
66 | log.verbose('This message contains additional details.');
67 | ```
68 |
69 | ---
70 |
71 | ### Logging a Debug Message
72 | To log a debug message during development, use the `debug` method:
73 |
74 | #### Example:
75 | ```ts
76 | log.debug('This is a debugging message.');
77 | ```
78 |
79 | ---
80 |
81 | ### Logging a Very Detailed Message
82 | To log a message with the highest level of detail, use the `silly` method:
83 |
84 | #### Example:
85 | ```ts
86 | log.silly('This is a highly detailed message.');
87 | ```
88 |
89 | ---
90 |
91 | ## Storing Logs
92 |
93 | ### Log File
94 | All logged messages are stored in a file named `app.log`.
95 | This file contains all the logged events and can be used for reviewing logs and analyzing system performance.
96 |
97 | #### Example of Log File Contents:
98 | ```
99 | [2024-11-28T14:32:00.000Z] [INFO] - The application started successfully.
100 | [2024-11-28T14:33:00.000Z] [ERROR] - An error occurred in the database.
101 | ```
102 |
103 | ---
104 |
105 | ## Conclusion
106 |
107 | **Kawkab Kawkab** provides a comprehensive and easy-to-use logging system, allowing developers to log messages at multiple levels with ease.
108 | You can use this system to track the system's state, identify potential issues, and analyze the application's performance.
109 |
110 | Start using the logging system today to make your application more stable and professional!
--------------------------------------------------------------------------------
/pages/en/digging-deeper/notifications.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Notification System in Kawkab
3 | description: A comprehensive guide to using the notification system in your app with the Kawkab framework.
4 | ---
5 |
6 | # Notification System in Kawkab
7 |
8 | The **notification system** in the **Kawkab** framework provides a simple yet powerful API for sending and managing notifications in your app. The system supports sending notifications through multiple channels such as email, SMS, and in-app notifications.
9 |
10 | ## Getting Started with the Notification System
11 |
12 | ### Creating a New Notification
13 |
14 | You can create a new notification using the built-in CLI command in Kawkab:
15 |
16 | ```bash
17 | npm run kawkab notification:make SendWelcomeNotification
18 | ```
19 |
20 | ### **Parameter Details:**
21 |
22 | - **``**: The name of the Notification you want to create.
23 | - **`[module]`**: The name of the module containing the Action (optional, default is `main`).
24 |
25 | ---
26 |
27 | Example:
28 |
29 | ```bash
30 | npm run kawkab notification:make [module]
31 | ```
32 |
33 | This command will generate a new notification file in the `notifications` folder with the required basic structure.
34 |
35 | ### Basic Notification Structure
36 |
37 | ```typescript
38 | import { BaseNotification, mail } from "kawkab";
39 |
40 | export class SendOtpCodeNotification extends BaseNotification {
41 | static async via() {
42 | await this.email();
43 | }
44 |
45 | static async email() {
46 | await mail.send({
47 | to: this.data.email,
48 | subject: "Hello!",
49 | body: "Welcome to our app!",
50 | });
51 | }
52 | }
53 | ```
54 |
55 | ## Key Features
56 |
57 | ### Defining Delivery Channels
58 |
59 | You can define one or more channels for sending the notification through the `via()` function:
60 |
61 | ```typescript
62 | static async via() {
63 | await this.email();
64 | }
65 | ```
66 |
67 | ## Best Practices
68 |
69 | 1. **Separation of Logic**: Ensure you separate the notification logic from the rest of the application logic.
70 | 2. **Use Templates**: Use templates for recurring messages to simplify maintenance and updates.
71 | 3. **Error Handling**: Implement appropriate error handling and log important events.
72 | 4. **Test Notifications**: Write tests to ensure the notification system works correctly.
73 |
74 | ## Conclusion
75 |
76 | The notification system in Kawkab provides a flexible and powerful solution for managing and sending notifications in your app. With support for multiple channels and custom templates, you can easily implement any specific notification requirements for your application.
--------------------------------------------------------------------------------
/pages/en/digging-deeper/queue.mdx:
--------------------------------------------------------------------------------
1 | # Queue System
2 |
3 | The queue system in the Kawkab framework provides an efficient way to handle background tasks. Two types of queue systems can be used:
4 |
5 | ## 1. Memory Queue
6 | This is the default system when `QUEUE_ENABLE_REDIS=false`. Tasks are stored directly in the application's memory.
7 |
8 | ### Features:
9 | - Easy to set up - no external services required
10 | - Suitable for local development and small applications
11 | - Tasks are lost when the application is restarted
12 |
13 | ## 2. Redis Queue
14 | Activated when `QUEUE_ENABLE_REDIS=true`. Redis is used as the task storage system.
15 |
16 | ### Configuration in `.env` file:
17 | ```env
18 | QUEUE_ENABLE_REDIS=true
19 | QUEUE_REDIS_HOST=127.0.0.1
20 | QUEUE_REDIS_PORT=6379
21 | ```
22 |
23 | ### Features:
24 | - High reliability - tasks are preserved even after restarting the application
25 | - Scalable - can handle a large number of tasks
26 | - Suitable for production and large applications
27 |
28 | ## Important Notes
29 | - Ensure that the Redis server is running if using the Redis queue
30 | - Queue settings can be modified in the `configuration.ts` file
31 | - Tasks are processed automatically in the background
--------------------------------------------------------------------------------
/pages/en/digging-deeper/settings.mdx:
--------------------------------------------------------------------------------
1 | # Settings in Kawkab Kawkab
2 |
3 | **Settings** provide an organized way to store values and keys used across the project to customize behaviors or enable/disable specific features. Kawkab Kawkab offers a powerful tool for easily and quickly creating settings files.
4 |
5 | ---
6 |
7 | ## Creating a Settings File
8 |
9 | To create a new settings file in Kawkab Kawkab, you can use the following command:
10 |
11 | ```bash
12 | setting:make [module]
13 | ```
14 |
15 | ### Parts:
16 | - **``**: The name of the settings file (e.g., `auth`).
17 | - **`[module]`**: The name of the module where the settings will be created. If no module is specified, the file is created in the default `main` module.
18 |
19 | ---
20 |
21 | ## Practical Example
22 |
23 | Suppose you want to create a settings file named `auth`, execute the following command:
24 |
25 | ```bash
26 | npm run kawkab setting:make auth
27 | ```
28 |
29 | ### Result:
30 | The following message will appear after execution:
31 |
32 | ```
33 | 🆗 Setting file 'auth' created successfully in module 'main'.
34 |
35 | 1️⃣ Your setting file is ready! You can now import it like this:
36 | 👉 import { setting } from '../settings/auth'
37 |
38 | 2️⃣ Use the setting like so:
39 | 👉 const enable:boolean = setting.enable
40 | ```
41 |
42 | ### What happened?
43 | 1. A new settings file named `auth` was created inside the default `main` module folder.
44 | 2. The file contains ready-to-use settings.
45 | 3. You can now import the settings and use them in your project.
46 |
47 | ---
48 |
49 | ## Using the Settings
50 |
51 | After creating the settings file, you can easily import and use it anywhere in your project.
52 |
53 | ### Example:
54 | #### Settings file: `auth.ts`
55 | ```ts
56 | export const setting = {
57 | enable: true, // Enable or disable authentication
58 | loginAttempts: 5, // Number of allowed login attempts
59 | timeout: 300, // Session timeout duration in seconds
60 | };
61 | ```
62 |
63 | #### Using the Settings:
64 | ```ts
65 | import { setting } from '../settings/auth';
66 |
67 | // Read a specific setting
68 | const isAuthEnabled = setting.enable;
69 | console.log(`Authentication Enabled: ${isAuthEnabled}`);
70 |
71 | // Use another setting
72 | if (setting.enable) {
73 | console.log(`Maximum Login Attempts: ${setting.loginAttempts}`);
74 | console.log(`Session Timeout: ${setting.timeout} seconds`);
75 | }
76 | ```
77 |
78 | ---
79 |
80 | ## Customizing the Module
81 |
82 | If you want to create a settings file within a specific module instead of the default `main` module, you can specify the module name during execution.
83 |
84 | ### Example:
85 | ```bash
86 | npm run kawkab setting:make database app
87 | ```
88 |
89 | ### Result:
90 | - A settings file named `database` will be created within the `app` module.
91 | - The resulting message:
92 | ```
93 | 🆗 Setting file 'database' created successfully in module 'app'.
94 |
95 | 1️⃣ Your setting file is ready! You can now import it like this:
96 | 👉 import { setting } from '../app/settings/database'
97 |
98 | 2️⃣ Use the setting like so:
99 | 👉 const maxConnections:number = setting.maxConnections
100 | ```
101 |
102 | ---
103 |
104 | ## Benefits of Using Settings
105 |
106 | 1. **Organizing core values**: Separating settings from core code to make them easier to manage.
107 | 2. **Customizability**: Easily modify settings to change app behavior without altering code.
108 | 3. **Reusability**: Unified settings can be used across different parts of the project.
109 | 4. **Ease of maintenance**: Fewer changes needed when updating settings compared to modifying the core code.
110 |
111 | ---
112 |
113 | ## Practical Tips
114 |
115 | - **Use descriptive names for settings**: Ensure that setting names reflect their purpose.
116 | - **Organize settings by module**: If working on a large project, it’s better to split settings into modules for easier management.
117 | - **Easily update settings**: Use settings files to avoid repeating values or modifying the core code when settings change.
118 |
119 | ---
120 |
121 | With this approach, you can easily and efficiently manage your project's settings in **Kawkab Kawkab** using the **Settings** tool.
--------------------------------------------------------------------------------
/pages/en/getting-started/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'installation': {
3 | title: 'Installation'
4 | },
5 | 'production': {
6 | title: 'Production'
7 | },
8 | 'directory-structure': {
9 | title: 'Directory Structure'
10 | },
11 | 'architecture': {
12 | title: 'Architecture'
13 | },
14 | 'file-based-routing': {
15 | title: 'File-Based Routing'
16 | },
17 | 'modules': {
18 | title: 'Modules'
19 | },
20 | 'mvc-architecture': {
21 | title: 'MVC Architecture'
22 | },
23 | 'hmvc-architecture': {
24 | title: 'HMVC Architecture'
25 | },
26 | 'configuration': {
27 | title: 'Configuration'
28 | },
29 | 'environment-variables': {
30 | title: 'Environment Variables'
31 | },
32 | }
--------------------------------------------------------------------------------
/pages/en/getting-started/architecture.mdx:
--------------------------------------------------------------------------------
1 | # **The Architecture of Kawkab**
2 |
3 | The **Kawkab** framework relies on the **HMVC** (Hierarchical Model-View-Controller) architecture to enhance project organization and scalability.
4 |
5 | ## **Overview**
6 |
7 | The HMVC architecture divides the project into distinct hierarchical modules, improving task separation and allowing for more flexible application organization. This architecture enables the building of complex applications in an organized and scalable manner.
8 |
9 | ## **Key Features**
10 |
11 | - **Modular Structure**: The project is organized into separate modules, each handling a specific function within the application.
12 | - **Main Module**: Kawkab includes a main module by default, serving as the core of the system.
13 | - **Scalability**: The modular design supports easy expansion and maintenance of the application.
14 |
15 | ## **Benefits**
16 |
17 | - **Improved Organization**: Dividing the project into clear modules enhances project organization and management.
18 | - **Enhanced Scalability**: Adding or updating features becomes more straightforward and smooth, promoting the project's long-term growth.
19 | - **Task Separation**: Each module focuses on specific aspects of the application, reducing complexity and increasing maintainability.
20 |
21 | By adopting the HMVC architecture, Kawkab provides a robust framework for building scalable and well-organized applications, facilitating the development of large and complex projects.
22 |
--------------------------------------------------------------------------------
/pages/en/getting-started/directory-structure.mdx:
--------------------------------------------------------------------------------
1 | # **Directory Structure in Kawkab**
2 |
3 | The **Kawkab** framework relies on an organized and advanced structure to support the flexible and efficient organization of all aspects of the application. This structure is designed to ensure high efficiency in development and ease of expansion in the long term.
4 |
5 | ## **📂 app**
6 | The main directory that contains the application logic. It includes the following core files:
7 |
8 | ### **📄 configuration.ts**
9 | Contains all application settings for the framework. It initializes the general services and basic configurations needed by different modules in the application.
10 |
11 | ### **📄 provider.ts**
12 | Includes the definition of the **Provider** that extends from `BaseProvider`, and is responsible for initialization and binding of all modules. The file includes the following functions:
13 |
14 | - **register()**: Called when the server and application start, used to register and initialize modules.
15 | - **boot()**: Called with each incoming request, used to initialize any additional services or settings required by each request.
16 |
17 | ### **📂 modules**
18 | Contains the different modules within the application. Each module is a folder that contains core components such as:
19 |
20 | - **📂 controllers**: Contains the logic that controls operations within the module.
21 | - **📂 services**: Contains the services or business logic specific to the module.
22 | - **📂 repositories**: Dedicated to interacting with databases or handling data.
23 | - **📄 module.ts**: The main file for the module that initializes and binds the module in the application, and handles its core functions.
24 |
25 | ## **📂 storage**
26 | Contains dedicated folders for storing files:
27 |
28 | ### **📂 private**
29 | Stores all sensitive files that must remain protected. This includes files that should not be accessible by any other party.
30 |
31 | ### **📂 public**
32 | Stores files that everyone is allowed to access through the application. These files are available for public use.
33 |
34 | ## **📄 .env**
35 | The environment file that contains sensitive variables specific to the application, such as API keys, database connection settings, and any sensitive information that should remain secret.
36 |
37 | ---
38 |
39 | ## **🔑 Key Points**
40 |
41 | - **configuration.ts**: Contains framework and application initialization settings.
42 | - **provider.ts**: Contains provider logic and module registration.
43 | - **modules**: Contains modules that include **controllers**, **services**, and **repositories**.
44 | - **storage**: Differentiates between public and private files through **private** and **public** folders.
45 | - **.env**: For storing sensitive variables used in the application environment.
46 |
47 | ---
48 |
49 | The **Kawkab** directory structure is designed to provide a flexible and secure development environment, ensuring high performance and ease of expansion in future applications.
50 |
--------------------------------------------------------------------------------
/pages/en/getting-started/file-based-routing.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: File-Based Routing
3 | description: Explanation of how the file-based routing system works in the Kawkab framework
4 | ---
5 |
6 | # File-Based Routing in Kawkab
7 |
8 | Kawkab uses a file-based routing system, a method that makes creating and managing application routes easier and more intuitive.
9 |
10 | ## How does it work?
11 |
12 | In Kawkab, routes are automatically defined based on the file structure within the `controllers` folder. Each file in this folder represents a route in your application.
13 |
14 | ### Simple Example
15 |
16 | ```
17 | app/
18 | └── main/
19 | └── controllers/
20 | ├── index.ts // represents "/"
21 | ├── about.ts // represents "/about"
22 | └── users/
23 | ├── index.ts // represents "/users"
24 | └── [id].ts // represents "/users/:id"
25 | ```
26 |
27 | ## Types of Routes
28 |
29 | ### 1. Static Routes
30 | ```typescript
31 | // app/modules/main/controllers/about.ts
32 |
33 | import { BaseController, req } from "kawkab";
34 |
35 | export default class extends BaseController {
36 | get() {
37 | return {
38 | message: "About Page"
39 | }
40 | }
41 | }
42 | ```
43 |
44 | ### 2. Dynamic Routes
45 | ```typescript
46 | // app/modules/main/controllers/users/[id].ts
47 |
48 | import { BaseController, req } from "kawkab";
49 |
50 | export default class extends BaseController {
51 | get() {
52 | const userId = req.var('id');
53 | return {
54 | message: `Viewing user number ${userId}`
55 | }
56 | }
57 | }
58 | ```
59 |
60 | ### 3. Nested Routes
61 | ```typescript
62 | // app/modules/main/controllers/blog/[category]/[post].ts
63 |
64 | import { BaseController, req } from "kawkab";
65 |
66 | export default class extends BaseController {
67 | get() {
68 | const { category, post } = req.vars();
69 | return {
70 | category,
71 | post
72 | }
73 | }
74 | }
75 | ```
76 |
77 | ## Supported HTTP Methods
78 |
79 | Kawkab supports all major HTTP methods:
80 |
81 | ```typescript
82 | export default class extends BaseController {
83 | // GET /users
84 | get() {
85 | return { message: "User list" }
86 | }
87 |
88 | // POST /users
89 | post() {
90 | return { message: "Create new user" }
91 | }
92 |
93 | // PUT /users
94 | put() {
95 | return { message: "Update user" }
96 | }
97 |
98 | // DELETE /users
99 | delete() {
100 | return { message: "Delete user" }
101 | }
102 | }
103 | ```
104 |
105 | ## Best Practices
106 |
107 | 1. **Organizing Routes**
108 | - Use logical folders to group related routes
109 | - Maintain a clear hierarchy
110 |
111 | 2. **Naming Files**
112 | - Use clear and descriptive names
113 | - Use square brackets for variables `[id]`
114 |
115 | 3. **Handling Errors**
116 | - Handle exceptions properly
117 | - Use appropriate HTTP status codes
118 |
119 | ## Full Example
120 |
121 | ```typescript
122 | // app/modules/main/controllers/api/products/[id]/reviews/[reviewId].ts
123 |
124 | import { BaseController, req } from "kawkab";
125 |
126 | export default class extends BaseController {
127 | // GET /api/products/1/reviews/5
128 | get() {
129 | const { id, reviewId } = req.vars();
130 | return {
131 | productId: id,
132 | reviewId: reviewId,
133 | message: "Viewing a specific review for a specific product"
134 | }
135 | }
136 |
137 | // POST /api/products/1/reviews
138 | post() {
139 | const { id } = req.vars();
140 | return {
141 | message: `Adding a new review for product ${id}`
142 | }
143 | }
144 | }
145 | ```
146 |
147 | ## Conclusion
148 |
149 | The file-based routing in Kawkab provides:
150 | - Better code organization
151 | - Easy understanding and maintenance
152 | - Flexibility in managing routes
153 | - Support for dynamic and nested routes
--------------------------------------------------------------------------------
/pages/en/getting-started/hmvc-architecture.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: HMVC Pattern in Kawkab
3 | description: A simplified explanation of the HMVC pattern in the Kawkab framework and how to use modules
4 | ---
5 |
6 | # HMVC Pattern in Kawkab
7 |
8 | The HMVC (Hierarchical Model-View-Controller) pattern is an extension of the traditional MVC pattern, where the application is organized into independent modules. In Kawkab, each module has its own MVC.
9 |
10 | ## What is HMVC?
11 |
12 | ### What is HMVC?
13 | - **H** stands for Hierarchical
14 | - **MVC** refers to the same basic components (Model, View, Controller)
15 | - Each module operates independently
16 | - Modules can communicate with each other
17 |
18 | ## Module Structure
19 |
20 | ```
21 | |── app/
22 | │ ├── main/ # Main module
23 | │ │ ├── controllers/
24 | │ │ ├── models/
25 | │ │ └── views/
26 | │ │
27 | │ ├── blog/ # Blog module
28 | │ │ ├── controllers/
29 | │ │ ├── models/
30 | │ │ └── views/
31 | │ │
32 | │ └── shop/ # Shop module
33 | │ ├── controllers/
34 | │ ├── models/
35 | │ └── views/
36 | ```
37 |
38 | ## Creating a New Module
39 |
40 | You can create a new module using the following command:
41 |
42 | ```bash
43 | npm run kawkab module:make blog
44 | ```
45 |
46 | ## Module Examples
47 |
48 | ### 1. Blog Module
49 | ```typescript
50 | // app/modules/blog/controllers/posts/index.ts
51 | export default class extends BaseController {
52 | get() {
53 | return {
54 | message: "Blog Posts",
55 | data: [
56 | { title: "First Post" },
57 | { title: "Second Post" }
58 | ]
59 | };
60 | }
61 | }
62 | ```
63 |
64 | ### 2. Shop Module
65 | ```typescript
66 | // app/modules/shop/controllers/products/index.ts
67 | export default class extends BaseController {
68 | get() {
69 | return {
70 | message: "Shop Products",
71 | data: [
72 | { name: "Product 1" },
73 | { name: "Product 2" }
74 | ]
75 | };
76 | }
77 | }
78 | ```
79 |
80 | ## Benefits of HMVC in Kawkab
81 |
82 | ### 1. Better Code Organization
83 | - Each module is independent
84 | - Easier management of large projects
85 | - Logical division of functionality
86 |
87 | ### 2. Code Reusability
88 | - A module can be reused in different projects
89 | - Shared functionality between modules
90 | - Reduces code duplication
91 |
92 | ### 3. Easier Maintenance
93 | - Modifying one module doesn't affect others
94 | - Testing each module independently
95 | - Easy updates to functionality
96 |
97 | ## Best Practices
98 |
99 | 1. **Logical Division of Modules**
100 | - Each module represents a distinct part of the application
101 | - Avoid overlapping between modules
102 |
103 | 2. **Independence**
104 | - Each module operates independently
105 | - Minimize dependencies between modules
106 |
107 | 3. **Reusability**
108 | - Design modules to be reusable
109 | - Share common components between modules
110 |
111 | ## Conclusion
112 |
113 | The HMVC pattern in Kawkab provides:
114 | - Better organization for large projects
115 | - Flexibility in managing modules
116 | - Scalability and maintainability
117 | - Code reusability
118 |
119 | You can start with the main module and then add new modules as needed for your project.
--------------------------------------------------------------------------------
/pages/en/getting-started/installation.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Installation Guide
3 | ---
4 |
5 | # **Installation Guide for the Kawkab Framework**
6 |
7 | The **Kawkab Framework** provides a flexible and powerful development environment for building modern web applications. In this guide, we will cover the steps to install **Kawkab** using **Node.js** and **Bun**.
8 |
9 | ## **Installation via Node.js**
10 |
11 | ### **Prerequisites:**
12 |
13 | Before you begin, make sure you have **Node.js** and **npm** installed on your device. To get the required version, you can download **Node.js** from the [official website](https://nodejs.org/), ensuring you are using version 18.0 or higher.
14 |
15 | ### **Create a New Project with Kawkab:**
16 |
17 | To start a new project using **Kawkab**, run the following command in the terminal:
18 |
19 | ```bash
20 | npx create-kawkab-app@latest init my-kawkab-app
21 | ```
22 |
23 | This command will create a new project named `app` inside a separate folder that contains all the necessary configuration files for **Kawkab**.
24 |
25 | ### **Navigate to the Project Folder:**
26 |
27 | Once the project is created, navigate to the folder using the following command:
28 |
29 | ```bash
30 | cd my-kawkab-app
31 | ```
32 |
33 | ### **Start the Development Server:**
34 |
35 | To start the local development server for **Kawkab**, use the following command:
36 |
37 | ```bash
38 | npm run dev
39 | ```
40 |
41 | The development server will run on the local link `http://localhost:3000`, allowing you to preview your application and test all features in real-time.
42 |
43 | ---
44 |
45 | Now your application is ready! **Kawkab** provides many built-in tools and features that help you build high-quality web applications quickly and efficiently.
46 |
47 | ## **Installation via Bun**
48 |
49 | If you prefer to use **Bun** as a fast and efficient **JavaScript runtime**, you can install **Kawkab** using the **Bun CLI** by following these steps:
50 |
51 | ### **Create a New Project with Kawkab via Bun:**
52 |
53 | ```bash
54 | bunx create-kawkab-app@latest init my-kawkab-app
55 | ```
56 |
57 | The rest of the steps are exactly the same as described in the **Node.js** installation method.
58 |
59 | ---
60 |
61 | ## **Conclusion**
62 |
63 | Now you can choose the method that suits you best to start building your application using **Kawkab**. Whether you're using **Node.js** or **Bun**, this framework offers you an integrated development environment to build modern, flexible, and scalable web applications.
64 |
65 | Start now and enjoy a seamless and powerful development experience!
--------------------------------------------------------------------------------
/pages/en/getting-started/mvc-architecture.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: MVC Pattern in Kawkab Kawkab
3 | description: A simple explanation of the MVC pattern in the Kawkab Kawkab framework
4 | ---
5 |
6 | # MVC Pattern in Kawkab Kawkab
7 |
8 | The MVC (Model-View-Controller) pattern is a design pattern that divides the application into three main parts. In Kawkab, you can use the `main` module to immediately start implementing this pattern, as it comes with the framework by default and contains everything you need.
9 |
10 | ## Key Components
11 |
12 | ### 1. Model
13 | - **M** stands for Model
14 | - Represents the data and business logic
15 | - Interacts with the database
16 | - Example:
17 | ```typescript
18 | // app/modules/main/models/User.ts
19 | export class User extends Model {
20 | // Contains the definition of data and business logic
21 | }
22 | ```
23 |
24 | ### 2. View
25 | - **V** stands for View
26 | - Represents the user interface
27 | - Displays data to the user
28 | - Example:
29 | ```typescript
30 | {
31 | "message": "Hello",
32 | "data": {
33 | "name": "Ahmed",
34 | "email": "ahmed@example.com"
35 | }
36 | }
37 | ```
38 |
39 | ### 3. Controller
40 | - **C** stands for Controller
41 | - Handles user requests
42 | - Controls the flow of data
43 | - Example:
44 | ```typescript
45 | // app/modules/main/controllers/users/index.ts
46 | export default class extends BaseController {
47 | // Handles requests and processes them
48 | get() {
49 | return {
50 | message: "Hello",
51 | data: {
52 | name: "Ahmed",
53 | email: "ahmed@example.com"
54 | }
55 | };
56 | }
57 | }
58 | ```
59 |
60 | ## Folder Structure in main
61 | ```
62 | app/
63 | ├── main/ # The main module - comes preconfigured with the app
64 | │ ├── controllers/ # Controllers (C)
65 | │ ├── models/ # Models (M)
66 | │ └── views/ # Views (V)
67 | ```
68 |
69 | ## Quick Start with main
70 |
71 | You can start directly by using the MVC pattern with the `main` module:
72 | 1. Models: Place your models in `main/models`
73 | 2. Controllers: Add your controllers in `main/controllers`
74 | 3. Views: Format the data in the controllers
75 |
76 | ## Conclusion
77 |
78 | The MVC pattern in Kawkab helps to:
79 | - Organize code logically
80 | - Separate responsibilities between components
81 | - Make maintenance and development easier
82 |
83 | With the default `main` module, you can start developing your app immediately without additional setup.
--------------------------------------------------------------------------------
/pages/en/getting-started/production.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Production
3 | ---
4 |
5 | # **Preparing for Production in Kawkab Framework**
6 |
7 | After developing your application using **Kawkab**, you'll need to deploy it in a production environment. This guide explains how to set up and run your application using the appropriate commands.
8 |
9 | ---
10 |
11 | ## **1. Build the Production Version**
12 |
13 | To prepare the application for the production environment, create a compressed and optimized build using the following command:
14 |
15 | ```bash
16 | npm run build
17 | ```
18 |
19 | This command will:
20 |
21 | - Generate the final files to be deployed on the server.
22 |
23 | The generated build will be saved in the `.dist` directory.
24 |
25 | ---
26 |
27 | ## **2. Run the Application in Production Mode**
28 |
29 | Once the build process is complete, you can run the application in production mode using the following command:
30 |
31 | ```bash
32 | npm run start
33 | ```
34 |
35 | ### **What this command does:**
36 | - Loads the final version of the project.
37 | - Starts the production server.
38 | - Makes the application available at the specified address (usually `http://localhost:3000`).
39 |
40 | ---
41 |
42 | ## **3. Important Tips for Production**
43 |
44 | ### **Environment Settings:**
45 | Ensure that the `.env.production` file contains the appropriate settings for production.
46 |
47 | ### **Reverse Proxy:**
48 | For better performance and security, consider placing a reverse proxy server like **Nginx** or **Apache** in front of your application.
49 |
50 | ---
51 |
52 | ## **Conclusion**
53 |
54 | Once the application is running in production mode, it will be ready to handle users. The **Kawkab** framework offers you flexible and efficient tools to ensure high performance and a great user experience.
55 |
56 | Enjoy productivity with **Kawkab**! 🚀
--------------------------------------------------------------------------------
/pages/en/preface/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'faqs': {
3 | title: 'FAQs',
4 | },
5 | 'governance': {
6 | title: 'Roles and Responsibilities',
7 | },
8 | 'releases': {
9 | title: 'Releases',
10 | },
11 | 'contribution-guide': {
12 | title: 'Contribution Guide',
13 | },
14 | }
--------------------------------------------------------------------------------
/pages/en/preface/contribution-guide.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Contribution Guidelines"
3 | description: "General contribution guidelines for all projects in the Kawkab Framework"
4 | ---
5 |
6 | # 🌟 **Contribution Guidelines for Kawkab Kawkab**
7 |
8 | We welcome contributions to all **Kawkab Kawkab** projects. Before contributing, please read these guidelines carefully.
9 |
10 | ## Ways to Contribute
11 | Programming is not the only way to contribute. Here are some other ways you can help the project and the community:
12 |
13 | - Fixing typos in the documentation
14 | - Improving existing documentation
15 | - Writing educational articles or blog posts to raise awareness among members
16 | - Assisting in issue triaging
17 | - Sharing your opinion on existing issues
18 | - Helping in the community via Discord or discussion forums
19 | - Reporting bugs
20 |
21 | ## Reporting Bugs
22 | Many issues reported in open-source projects are often user-side setup issues or questions. We strongly recommend properly diagnosing the issue before reporting it.
23 |
24 | ### How to Report an Issue:
25 | - **Ideal Issue**: Isolate the core bug, create a failing test within the repository, and open an issue on GitHub about it.
26 | - **Good Issue**: Isolate the core bug and provide a minimal reproduction on a GitHub repository.
27 | - **Reasonable Issue**: Properly identify the problem and share the code that caused the issue.
28 |
29 | ## Getting Started with Contributions
30 | If you want to make a contribution through a Pull Request, it is preferred to start with a discussion to understand the project better before working on the code.
31 |
32 | - If you’re fixing a bug: The issue should have been confirmed as a bug.
33 | - If you’re adding a new feature: Please explain why the feature is needed.
34 |
35 | ## Setting Up the Repository
36 | To get started, clone the repository to your local machine:
37 |
38 | ```bash
39 | git clone
40 | npm install
41 | ```
42 |
43 | To run tests:
44 |
45 | ```bash
46 | npm test
47 | ```
48 |
49 | ## Tools Used
50 | Here are the tools used across all projects:
51 |
52 | | Tool | Purpose |
53 | |----------------|-------------------------------------------------|
54 | | TypeScript | All repositories are written in TypeScript. |
55 | | ESLint | Ensures code style consistency across repositories. |
56 | | Prettier | Formats code uniformly. |
57 |
58 | ## Code Formatting
59 | Before pushing your code to the repository, ensure it is formatted using the following tools:
60 |
61 | - To format code with Prettier:
62 | ```bash
63 | npm run format
64 | ```
65 | - To lint code with ESLint:
66 | ```bash
67 | npm run lint
68 | ```
69 |
70 | ## How to Get Recognized as a Contributor
71 | We rely on GitHub to showcase all contributors to the repository. If your contribution is significant, your name will be included in the release notes.
--------------------------------------------------------------------------------
/pages/en/preface/faqs.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Frequently Asked Questions"
3 | description: "Answers to the most common questions about Kawkab Kawkab"
4 | ---
5 |
6 | # ❓ **Frequently Asked Questions (FAQs)**
7 |
8 | ### Who develops Kawkab Kawkab?
9 | **Kawkab Kawkab** is an open-source framework developed by **@Hassan Kerdash**. The framework is continuously maintained and improved by the core team and community contributors.
10 |
11 | The lead developer, **@Hassan Kerdash**, is the project leader and actively works on enhancing the framework.
12 |
13 | ### How is Kawkab Kawkab funded?
14 | Kawkab Kawkab is an open-source project funded through donations and community contributions. If you or your company benefit from using Kawkab Kawkab, you can support the project by donating via platforms such as **PayPal** or **Patreon**.
15 |
16 | ### Is Kawkab Kawkab reliable and well-maintained?
17 | Yes! Kawkab Kawkab is used by many developers and companies worldwide. The lead developer continuously works on improving and maintaining the framework to ensure high quality and performance.
18 |
19 | We consistently enhance the documentation, add new features, and improve the codebase.
20 |
21 | ### Is Kawkab Kawkab fast?
22 | Yes, Kawkab Kawkab focuses on solving real-world problems rather than chasing the best performance in benchmarks. However, we continually work on improving performance in the most critical areas. For instance:
23 |
24 | - The HTTP server in Kawkab Kawkab performs on par with well-known frameworks like Fastify.
25 | - Kawkab Kawkab's validation layer offers better performance than many other validation libraries in the **Node.js** ecosystem.
26 |
27 | ### Do you offer paid support?
28 | Yes, we offer premium support for projects that require consultation or additional assistance. You can learn more about the priority support program via [our GitHub page](https://github.com/HassanKerdash/kawkab).
29 |
30 | ### How can I stay updated with Kawkab Kawkab?
31 | You can follow Kawkab Kawkab through the following links to stay informed about the latest updates:
32 |
33 | - [Discord server](https://discord.gg)
34 | - [X (Twitter)](https://twitter.com)
35 | - [GitHub discussions](https://github.com/HassanKerdash/kawkab/discussions)
36 | - [Blog and newsletter](https://blog.kawkab.io)
37 |
38 | © Kawkab Kawkab
--------------------------------------------------------------------------------
/pages/en/preface/governance.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Managing Kawkab Framework"
3 | description: "Roles and responsibilities within the Kawkab Framework project"
4 | ---
5 |
6 | # 🏛️ **Managing Kawkab Framework**
7 |
8 | ### **Authors**
9 | **@Hassan Kerdash** is the author of **Kawkab Framework**, responsible for managing the project, setting development standards, and determining the project's overall direction. This includes:
10 |
11 | - Deciding on new projects to be included in the Kawkab Framework.
12 | - Assigning project leaders, guiding them as needed, and transferring leadership when a current leader steps down.
13 | - Documenting the framework's vision and sharing it with other leaders and the community.
14 |
15 | ### **Project Leaders**
16 | The Kawkab Framework consists of a set of packages created and managed by the core team. Each package has a project leader assigned by the author.
17 |
18 | In most cases, the package creator becomes the project leader due to their initial efforts in developing the idea.
19 |
20 | - The leader is the person who makes the final decisions on all aspects of the project.
21 | - The leader is responsible for setting the strategic goals of the project and clearly communicating them to the community.
22 | - The leader must also interact with the community to address their diverse needs and ensure the long-term sustainability of the project.
23 |
24 | ### **Core Team**
25 | Core team members are contributors who have made significant contributions to the project and are relied upon for writing code and conducting reviews.
26 |
27 | - Core team members are often tasked with specific responsibilities, such as fixing bugs, developing new features, or improving documentation.
28 | - They do not have the authority to make decisions for the entire project but often have a significant impact on its direction.
29 |
30 | ### **Active Core Team Members**
31 | Active core team members contribute regularly to the project, handling tasks such as reviewing issues, fixing bugs, or improving documentation.
32 |
33 | ### **Honorary Core Team Members**
34 | Some members who have made significant contributions in the past may no longer be able to participate at the same level. These members are honored with the title of "Honorary Core Team Members" and are welcome to contribute whenever they choose.
35 |
36 | ### **Contributors**
37 | Contributors are community members who do not seek to become part of the core team but still provide valuable input, such as reporting bugs, adding new features, or improving the project's infrastructure.
38 |
39 | Contributing does not require commitment or specific skills, and anyone can become a contributor simply by working on useful tasks for the project.
40 |
41 | ### **Users**
42 | Users are the most important members of the community. Without them, the project would have no purpose. Anyone can be a user, with no specific requirements.
43 |
44 | Users should be encouraged to engage with the community, such as spreading the word about the project or offering moral support.
45 |
46 | ### **Support**
47 | We encourage all community members to provide support to new users. This support is voluntary and provided through the project's designated channels.
48 |
49 | ### **Financial Donations**
50 | In open-source projects, financial donations are not as important as active contributions but remain a valuable option for individuals or organizations that lack time but have the financial capacity to support the project.
51 |
52 | You can support us through donations on platforms like **GitHub Sponsors**.
53 |
54 | ### **Trademark and Ownership**
55 | **Kawkab Framework** is a trademark referring to the framework under the name **@Hassan Kerdash**. The name or logo of Kawkab Framework must not be used in a way that could mislead users or imply an unofficial affiliation with the project.
56 |
57 | ### **Projects Under Kawkab Framework**
58 | Projects that join the **Kawkab Framework** become intellectual property of the author. Once a project is added under the Kawkab Framework umbrella, the leader cannot delete or abandon the project.
--------------------------------------------------------------------------------
/pages/en/preface/releases.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Releases"
3 | description: "Key releases of the core and related packages in the framework"
4 | ---
5 |
6 | # 🚀 **Releases**
7 |
8 | Below are the major releases for the framework and the ecosystem packages maintained by the **Kawkab Kawkab** core team.
9 |
10 | | Package | Change Description | Release Date |
11 | |--------------------------------|--------------------------------------------------------|--------------------|
12 | | `kawkab@1.0.0-alpha.2` | Initial alpha release for testing and exploration | December 9, 2024 |
13 | | `create-kawkab-app@1.0.0-alpha.2` | Initial alpha release of the installation and setup tool | December 9, 2024 |
14 |
15 | ### Release Notes
16 | - **Major Releases**: Include significant changes that might require code modifications.
17 | - **Minor Releases**: Contain small enhancements or new features.
18 | - **Patch Releases**: Dedicated to fixing bugs or improving performance.
19 |
20 | ### Support
21 | If you encounter any issues or have questions regarding the releases, feel free to reach out through our official support channels.
--------------------------------------------------------------------------------
/pages/en/security/_meta.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 'input-validation': {
3 | title: "Input Validation",
4 | },
5 | 'encryption': {
6 | title: "Encryption",
7 | },
8 | 'hashing': {
9 | title: "Hashing",
10 | },
11 | 'password': {
12 | title: "Passwords",
13 | },
14 | 'rate-limiter': {
15 | title: "Rate Limiting",
16 | },
17 | 'auth': {
18 | title: "Authentication",
19 | },
20 | };
--------------------------------------------------------------------------------
/pages/en/security/password.mdx:
--------------------------------------------------------------------------------
1 | # Handling **Passwords** in Kawkab
2 |
3 | In the world of modern application development, **password protection** is crucial to ensure the security of user data. In the **Kawkab** framework, we provide custom functions to easily and securely hash and verify passwords.
4 |
5 | ---
6 |
7 | ## **What is the Password Protection Process?**
8 |
9 | Password protection involves converting plain text passwords into **encrypted hash values** using strong algorithms.
10 | ### Features of this process:
11 | 1. **Non-readability**: The hashed password cannot be read directly.
12 | 2. **Security consistency**: Secure algorithms are used to ensure data protection.
13 | 3. **Quick verification**: The password can be verified without knowing the original text.
14 |
15 | ---
16 |
17 | ## **Password Functions in Kawkab**
18 |
19 | ### 1. **`hash`**
20 | A function used to generate an **encrypted hash of the password**.
21 | - It uses advanced algorithms to generate the hash.
22 | - It is recommended to use this during the registration or password update process.
23 |
24 | #### **Example:**
25 | ```ts
26 | import { password } from "kawkab";
27 |
28 | const myPassword = "MySecurePassword123";
29 | const hashedPassword = await password.hash(myPassword);
30 |
31 | console.log(hashedPassword);
32 | // Output: A hashed string like: "$2b$10$XfT...9lmJ"
33 | ```
34 |
35 | #### **Additional Options:**
36 | You can customize the encryption strength (Salt Rounds) to ensure more security.
37 | ```ts
38 | const strongHash = await password.hash(password, 12);
39 | ```
40 |
41 | ---
42 |
43 | ### 2. **`verify`**
44 | A function used to compare the entered password with the stored hash to verify its validity.
45 | - It is used during login or other operations that require verification.
46 |
47 | #### **Example:**
48 | ```ts
49 | import { password } from "kawkab";
50 |
51 | const myPassword = "MySecurePassword123";
52 | const hashedPassword = await password.hash(myPassword);
53 |
54 | const isValid = await password.verify(myPassword, hashedPassword);
55 |
56 | if (isValid) {
57 | console.log("Password is correct.");
58 | } else {
59 | console.log("Password is incorrect.");
60 | }
61 | ```
62 |
63 | ---
64 |
65 | ## **Practical Uses of Passwords in Applications**
66 |
67 | ### **1. Registering New Users**
68 | When registering a user, the password is hashed before storing it in the database.
69 | ```ts
70 | import { password } from "kawkab";
71 |
72 | async function registerUser(username: string, password: string) {
73 | const hashedPassword = password.hash(password);
74 | console.log(`User ${username} has been registered with an encrypted password: ${hashedPassword}`);
75 | }
76 |
77 | registerUser("Hassan", "Password123!");
78 | ```
79 |
80 | ---
81 |
82 | ### **2. Logging In**
83 | When attempting to log in, the entered password is compared to the stored hash.
84 | ```ts
85 | import { password } from "kawkab";
86 |
87 | async function loginUser(inputPassword: string, storedHash: string) {
88 | const isMatch = await password.verify(inputPassword, storedHash);
89 |
90 | if (isMatch) {
91 | console.log("Logged in successfully.");
92 | } else {
93 | console.log("Incorrect password.");
94 | }
95 | }
96 |
97 | // Example
98 | loginUser("Password123!", "$2b$10$XfT...9lmJ");
99 | ```
100 |
101 | ---
102 |
103 | ## **Comparison of `hash` and `verify`**
104 |
105 | | Function | Inputs | Output | Usage |
106 | |--------------|----------------------------|--------------------|---------------------------------|
107 | | **`hash`** | Plain text password | Hashed password | Hashing passwords during registration |
108 | | **`verify`** | Plain text password + hash | `true` or `false` | Verification during login |
109 |
110 | ---
111 |
112 | ## **Practical Tips**
113 | - **Do not store passwords as plain text.** Always use the `hash` function to encrypt them.
114 | - Set the number of salt rounds between 10-14 for a balance between performance and security.
115 | - During verification, only use the `verify` function to compare passwords.
116 |
117 | ---
118 |
119 | By using the **Kawkab** functions dedicated to password protection, you can ensure a high level of security for your users and reduce security risks.
--------------------------------------------------------------------------------
/pages/en/security/rate-limiter.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Rate Limiter
3 | description: How to configure and control request rates using the Rate Limiter system in Kawkab JS.
4 | ---
5 |
6 | # Rate Limiter in Kawkab JS
7 |
8 | A **Rate Limiter** is used to control the number of requests a client can send to the server within a specific time period. This helps prevent attacks like **Denial of Service (DoS)** and protects your application from excessive resource consumption due to repeated requests from the same client.
9 |
10 | ### Configuring Rate Limiter
11 |
12 | You can configure the **Rate Limiter** settings through the main configuration file `app/configuration.ts`. This file provides full control over the maximum number of allowed requests and the time window for each client.
13 |
14 | #### Rate Limiter Settings
15 |
16 | ```typescript
17 | import { env } from "kawkab";
18 | import { Provider } from "./provider";
19 |
20 | // Main configuration object for the application
21 | export const app = {
22 | // Rate limiter configuration
23 | rateLimiter: {
24 | // Enable or disable the rate limiter
25 | enable: true,
26 |
27 | // Maximum number of requests allowed within the defined time window
28 | maxRequests: 100,
29 |
30 | // Time window (in milliseconds) for rate limiting, default is 1 minute (60 * 1000)
31 | windowTime: 60 * 1000,
32 |
33 | // Error code sent when rate limit is exceeded
34 | code: "too-many-requests",
35 |
36 | // Message displayed when rate limit is exceeded
37 | message: "Too many requests. Please try again later.",
38 | },
39 | };
40 | ```
41 |
42 | ### Explanation of Settings:
43 |
44 | - **`enable`**: Determines whether the Rate Limiter is enabled or not. If set to `true`, the system is activated. If set to `false`, it is disabled.
45 | - **`maxRequests`**: The maximum number of requests that a user can send within a specified time period (defined by the `windowTime`).
46 | - **`windowTime`**: The time window (in milliseconds) within which the request rate is limited. The default is 60 seconds (60,000 milliseconds).
47 | - **`code`**: The error code that will be sent as a response when the client exceeds the allowed request limit.
48 | - **`message`**: The message that will be displayed to the user when the request limit is exceeded.
49 |
50 | ### Summary
51 |
52 | The **Rate Limiter** helps protect your application from attacks based on sending large numbers of requests in a short period. With customizable settings in `configuration.ts`, you can define the maximum number of requests and the time window during which requests are allowed. This improves server security and enhances the user experience.
53 |
54 | ---
55 |
56 | **Note:** Ensure that the **Rate Limiter** settings align with your application’s needs and the volume of traffic you expect.
--------------------------------------------------------------------------------
/public/ar/brands/tiqniaat.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/ar/brands/tiqniaat.png
--------------------------------------------------------------------------------
/public/ar/contributors/1446-05-21-22-12-00-5b2f8138.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/ar/contributors/1446-05-21-22-12-00-5b2f8138.jpg
--------------------------------------------------------------------------------
/public/ar/contributors/555454465656543544.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/ar/contributors/555454465656543544.png
--------------------------------------------------------------------------------
/public/ar/contributors/555656543454465434544.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/ar/contributors/555656543454465434544.png
--------------------------------------------------------------------------------
/public/ar/contributors/556565434544.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/ar/contributors/556565434544.png
--------------------------------------------------------------------------------
/public/ar/contributors/female.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/ar/contributors/female.png
--------------------------------------------------------------------------------
/public/en/brands/tiqniaat.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/en/brands/tiqniaat.png
--------------------------------------------------------------------------------
/public/en/contributors/1446-05-21-22-12-00-5b2f8138.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/en/contributors/1446-05-21-22-12-00-5b2f8138.jpg
--------------------------------------------------------------------------------
/public/en/contributors/555454465656543544.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/en/contributors/555454465656543544.png
--------------------------------------------------------------------------------
/public/en/contributors/555656543454465434544.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/en/contributors/555656543454465434544.png
--------------------------------------------------------------------------------
/public/en/contributors/556565434544.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/en/contributors/556565434544.png
--------------------------------------------------------------------------------
/public/en/contributors/female.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/kawkabjs/docs/34519948f62c53baf8d55849ca58f16f3ff64a91/public/en/contributors/female.png
--------------------------------------------------------------------------------
/styles.css:
--------------------------------------------------------------------------------
1 | @import url('https://fonts.googleapis.com/css2?family=Alexandria:wght@100..900&display=swap');
2 |
3 | body {
4 | font-family: 'Alexandria', sans-serif;
5 | }
6 |
--------------------------------------------------------------------------------
/theme.config.tsx:
--------------------------------------------------------------------------------
1 | import React from "react";
2 |
3 | export default {
4 | logo: Kawkab JS,
5 | project: {
6 | link: "https://github.com/kawkabjs/docs",
7 | },
8 | footer: {
9 | content: (
10 |
11 | MIT {new Date().getFullYear()} ©{' '}
12 |
13 | Kawkab JS
14 |
15 | .
16 |
17 | )
18 | },
19 | i18n: [
20 | { locale: 'en', name: 'English' },
21 | { locale: 'ar', name: 'العربية', direction: 'rtl' },
22 | ]
23 | };
24 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "target": "ES2017",
4 | "lib": [
5 | "dom",
6 | "dom.iterable",
7 | "esnext"
8 | ],
9 | "allowJs": true,
10 | "skipLibCheck": true,
11 | "strict": false,
12 | "noEmit": true,
13 | "incremental": true,
14 | "module": "esnext",
15 | "esModuleInterop": true,
16 | "moduleResolution": "node",
17 | "resolveJsonModule": true,
18 | "isolatedModules": true,
19 | "jsx": "preserve"
20 | },
21 | "include": [
22 | "next-env.d.ts",
23 | "**/*.ts",
24 | "**/*.tsx"
25 | , "pages/ar/security/rate-limiter.mdx" ],
26 | "exclude": [
27 | "node_modules"
28 | ]
29 | }
30 |
--------------------------------------------------------------------------------