curl -fsSL https://bun.sh/install | bash

# إضافة مستودع Bun إلى Homebrew
brew tap oven-sh/bun

# تثبيت Bun
brew install bun

# سحب الصورة الرسمية
docker pull oven/bun

# تشغيل حاوية Bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

# تثبيت WSL2 من PowerShell (بصلاحيات المسؤول)
wsl --install

curl -fsSL https://bun.sh/install | bash

curl -fsSL https://bun.sh/install | BUN_INSTALL_VERSION="0.5.9" bash

# التحقق من الإصدار المثبت
bun --version

# عرض معلومات النظام والبيئة
bun --info

أساسيات تشغيل الملفات

يمكن استخدام Bun.js لتشغيل ملفات JavaScript وTypeScript وJSX مباشرة دون الحاجة إلى خطوات تجميع مسبقة:

تشغيل ملف JavaScript

لتشغيل ملف JavaScript، استخدم الأمر التالي:

bun run hello.js

مثال لمحتوى ملف JavaScript بسيط (hello.js):

// hello.js
console.log("Hello from Bun.js!");

// استخدام وظائف غير متزامنة 
async function fetchData() {
  const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");
  const data = await response.json();
  console.log("Fetched data:", data);
}

fetchData();

تشغيل ملف TypeScript

يمكن تشغيل ملفات TypeScript مباشرة دون الحاجة لتحويلها أولاً:

bun run hello.ts

مثال لمحتوى ملف TypeScript (hello.ts):

// hello.ts
interface User {
  id: number;
  name: string;
  email: string;
}

async function getUser(id: number): Promise {
  const response = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`);
  return await response.json();
}

async function main() {
  try {
    const user = await getUser(1);
    console.log(`User: ${user.name} (${user.email})`);
  } catch (error) {
    console.error("Error fetching user:", error);
  }
}

main();

الأمر المختصر

يمكن استخدام bun مباشرة بدلاً من bun run كاختصار لتشغيل الملفات:

bun hello.js
bun hello.ts

الميزات الأساسية لبيئة التشغيل

استيراد الوحدات (Modules)

يدعم Bun.js كلاً من ES Modules وCommonJS:

// استيراد بصيغة ES Modules
import fs from 'fs';
import { readFile } from 'fs/promises';

// استيراد بصيغة CommonJS (يدعم أيضاً)
const path = require('path');

وحدات مدمجة خاصة ببن

يوفر Bun.js وحدات مدمجة خاصة به يمكن استيرادها باستخدام بادئة bun::

// استيراد وحدة الاختبار المدمجة
import { test, expect } from 'bun:test';

// استيراد وحدة الملفات الثنائية
import { BinaryData } from 'bun:binary';

وضع المراقبة (Watch Mode)

يمكن تشغيل الملفات في وضع المراقبة، حيث يعيد Bun.js تشغيل التطبيق تلقائياً عند تغيير الملفات:

bun --watch index.ts

استخدام واجهات برمجة الويب القياسية

يوفر Bun.js دعماً لواجهات برمجة الويب القياسية مثل Fetch و Request و Response و Headers و URL وغيرها:

// استخدام Fetch API
const response = await fetch('https://example.com/api');
const data = await response.json();

// استخدام URL API
const url = new URL('https://example.com/search');
url.searchParams.set('q', 'bun js');
console.log(url.toString()); // https://example.com/search?q=bun%20js

// استخدام Headers API
const headers = new Headers();
headers.set('Content-Type', 'application/json');
headers.set('Authorization', 'Bearer token123');

الوصول إلى متغيرات البيئة

يمكن الوصول إلى متغيرات البيئة عبر process.env أو Bun.env:

// استخدام متغيرات البيئة
console.log(process.env.NODE_ENV); // متوافق مع Node.js
console.log(Bun.env.NODE_ENV);     // وصول مباشر من كائن Bun

إنشاء مشروع جديد

يوفر Bun.js أمراً لإنشاء مشاريع جديدة باستخدام قوالب متعددة:

# إنشاء مشروع باستخدام القالب الافتراضي
bun create empty-project my-project

# إنشاء مشروع React
bun create react my-react-app

# إنشاء مشروع Next.js
bun create next my-next-app

# إنشاء مشروع React مع TypeScript
bun create react-ts my-react-ts-app

المجمّع (Bundler)

يتضمن Bun.js مجمّعاً (bundler) مدمجاً يمكن استخدامه لتجميع وحزم ملفات JavaScript وTypeScript:

التجميع الأساسي

لتجميع ملف وجميع وحداته:

# تجميع ملف index.ts وإخراج النتيجة في مجلد dist
bun build ./index.ts --outdir ./dist

تصغير الكود

يمكن تصغير الكود الناتج لتحسين الأداء وتقليل الحجم:

# تجميع مع تصغير
bun build ./index.ts --outdir ./dist --minify

تحويل إلى منصات محددة

يمكن تحديد المنصة المستهدفة للكود الناتج:

# تحويل إلى كود مناسب للمتصفح
bun build ./index.ts --outdir ./dist --target browser

# تحويل إلى كود مناسب للتشغيل في بيئة Node.js
bun build ./index.ts --outdir ./dist --target node

إنشاء حزمة قابلة للتنفيذ

يمكن إنشاء ملف تنفيذي مستقل من الكود المصدري:

# إنشاء ملف تنفيذي
bun build ./cli.ts --compile --outfile mycli

تكوين الحزم (Bundling Configuration)

يمكن تحديد خيارات التجميع المتقدمة باستخدام ملف تكوين:

// bunfig.toml
[bundle]
entrypoints = ["./src/index.ts"]
outdir = "./dist"
minify = true
target = "browser"
format = "esm"
sourcemap = "external"

ثم تنفيذ التجميع باستخدام التكوين المحدد:

bun build

إنشاء خادم HTTP بسيط

لإنشاء خادم HTTP بسيط في Bun.js، يمكنك استخدام دالة serve المدمجة:

// server.js - خادم بسيط
import { serve } from "bun";

const server = serve({
port: 3000, // المنفذ الافتراضي هو 3000
fetch(req) {
return new Response("مرحباً بالعالم من Bun.js!");
},
});

console.log(`الخادم يعمل الآن على المنفذ ${server.port}`);

يمكن تشغيل هذا الخادم باستخدام:

bun run server.js

معالجة الطلبات

تتبع واجهة برمجة التطبيقات معيار Fetch API، مما يعني أنك تتعامل مع كائنات Request و Response القياسية:

// التعامل مع طرق الطلب المختلفة والمسارات
const server = serve({
fetch(req) {
const url = new URL(req.url);
const method = req.method;

// معالجة المسارات المختلفة
if (url.pathname === "/") {
return new Response("الصفحة الرئيسية");
}

if (url.pathname === "/api/users" && method === "GET") {
// إرجاع بيانات بتنسيق JSON
return Response.json({
users: [
{ id: 1, name: "أحمد" },
{ id: 2, name: "سارة" },
{ id: 3, name: "محمد" }
]
});
}

if (url.pathname === "/api/users" && method === "POST") {
// يمكن معالجة البيانات المرسلة من النموذج
return new Response("تم إنشاء المستخدم بنجاح", { status: 201 });
}

// إرجاع استجابة 404 لأي مسار غير معروف
return new Response("الصفحة غير موجودة", { status: 404 });
}
});

استخراج بيانات الطلب

يمكن استخراج البيانات من طلبات POST وPUT بطرق متعددة:

// استخراج بيانات من طلب POST
if (url.pathname === "/api/submit" && method === "POST") {
// قراءة بيانات JSON
const jsonData = await req.json();
console.log("بيانات JSON:", jsonData);

// أو قراءة نص عادي
// const text = await req.text();

// أو قراءة بيانات النموذج
// const formData = await req.formData();
// const username = formData.get("username");

// أو قراءة بيانات ثنائية
// const buffer = await req.arrayBuffer();

return Response.json({ success: true });
}

إرسال ملفات

يمكن إرسال ملفات بسهولة باستخدام كائن Bun.file:

// إرسال ملف
if (url.pathname === "/download") {
const file = Bun.file("./files/document.pdf");
return new Response(file, {
headers: {
"Content-Type": "application/pdf",
"Content-Disposition": "attachment; filename=document.pdf"
}
});
}

// إرسال صورة
if (url.pathname === "/image.jpg") {
const image = Bun.file("./images/photo.jpg");
return new Response(image, {
headers: { "Content-Type": "image/jpeg" }
});
}

// إرسال صفحة HTML
if (url.pathname === "/page") {
const html = Bun.file("./public/page.html");
return new Response(html, {
headers: { "Content-Type": "text/html" }
});
}

دعم WebSockets

توفر Bun.js دعماً مدمجاً لبروتوكول WebSockets، مما يتيح إنشاء تطبيقات تفاعلية في الوقت الحقيقي:

// مثال لخادم WebSocket
import { serve } from "bun";

const server = serve({
fetch(req, server) {
// التحقق من أن الطلب هو طلب ترقية WebSocket
if (req.headers.get("Upgrade") === "websocket") {
// محاولة ترقية الاتصال
const success = server.upgrade(req);
if (success) {
// تمت الترقية بنجاح، لا حاجة لإرجاع استجابة HTTP
return;
}
return new Response("فشلت ترقية WebSocket", { status: 400 });
}

return new Response("هذا خادم WebSocket، استخدم بروتوكول WebSocket للاتصال.");
},
// معالجة أحداث WebSocket
websocket: {
// عندما يتم فتح اتصال جديد
open(ws) {
console.log("اتصال جديد!");
ws.send("مرحباً بك في خادم WebSocket!");
},
// عندما تصل رسالة من العميل
message(ws, message) {
console.log(`استلام رسالة: ${message}`);

// إعادة إرسال الرسالة إلى العميل
ws.send(`استلمت رسالتك: ${message}`);

// يمكن إرسال الرسالة لجميع العملاء المتصلين
// server.publish("channel", `رسالة جديدة: ${message}`);
},
// عندما يتم إغلاق الاتصال
close(ws, code, reason) {
console.log(`تم إغلاق الاتصال: ${code} ${reason}`);
}
}
});

console.log(`خادم WebSocket يعمل على المنفذ ${server.port}`);

مثال لعميل WebSocket (في المتصفح)

// كود العميل في JavaScript
const socket = new WebSocket("ws://localhost:3000");

// عند فتح الاتصال
socket.onopen = () => {
console.log("تم الاتصال بالخادم");
socket.send("مرحباً من العميل!");
};

// عند استلام رسالة
socket.onmessage = (event) => {
console.log("رسالة من الخادم:", event.data);
};

// عند إغلاق الاتصال
socket.onclose = () => {
console.log("تم إغلاق الاتصال");
};

// عند حدوث خطأ
socket.onerror = (error) => {
console.error("خطأ في الاتصال:", error);
};

# تثبيت حزمة
bun install express

# تثبيت حزمة كاعتماد تطوير
bun install --dev typescript
# أو بشكل مختصر
bun install -d typescript

# تثبيت حزم متعددة
bun install react react-dom next

# تثبيت حزمة (مختصر)
bun add express

# تثبيت كاعتماد تطوير (مختصر)
bun add -d typescript

# تحديث جميع الحزم
bun update

# تحديث حزمة محددة
bun update express

# إزالة حزمة
bun remove express

{
"name": "my-project",
"version": "1.0.0",
"scripts": {
"dev": "bun run --watch src/index.ts",
"start": "bun run src/index.ts",
"build": "bun build src/index.ts --outdir dist",
"test": "bun test"
}
}

# تشغيل سكربت dev
bun run dev

# تشغيل سكربت start
bun run start

# تشغيل eslint مباشرة دون تثبيته محلياً
bun x eslint src/

# تشغيل أداة أخرى
bun x cowsay "مرحباً بالعالم"

// قراءة ملف باستخدام Bun.file
const file = Bun.file("path/to/file.txt");

// قراءة كنص
const text = await file.text();
console.log(text);

// قراءة كبيانات JSON
const jsonFile = Bun.file("path/to/config.json");
const config = await jsonFile.json();
console.log(config.name);

// قراءة كبيانات ثنائية
const binaryFile = Bun.file("path/to/image.png");
const data = await binaryFile.arrayBuffer();

// قراءة كـ Blob
const blob = await file.blob();

// كتابة نص إلى ملف
await Bun.write("path/to/file.txt", "محتوى الملف");

// كتابة بيانات JSON
const data = { name: "Ahmed", age: 30 };
await Bun.write("path/to/data.json", JSON.stringify(data, null, 2));

// كتابة بيانات ثنائية
const buffer = new Uint8Array([0, 1, 2, 3, 4]);
await Bun.write("path/to/binary.dat", buffer);

// كتابة من Blob أو Response
const response = await fetch("https://example.com/image.jpg");
const blob = await response.blob();
await Bun.write("image.jpg", blob);

// التحقق من وجود ملف
const file = Bun.file("path/to/file.txt");
const exists = await file.exists();

if (exists) {
console.log("الملف موجود");
} else {
console.log("الملف غير موجود");
}

// استيراد وحدات النظام المتوافقة مع Node.js
import { mkdir, readdir, stat, rm } from "fs/promises";

// إنشاء مجلد
await mkdir("./uploads", { recursive: true });

// قراءة محتويات مجلد
const files = await readdir("./src");
console.log(files);

// الحصول على معلومات مفصلة عن الملفات
const entries = await readdir("./src", { withFileTypes: true });
for (const entry of entries) {
console.log(`${entry.name} - ${entry.isDirectory() ? "مجلد" : "ملف"}`);
}

// حذف ملف أو مجلد
await rm("./temp", { recursive: true, force: true });

import { join, resolve, dirname, basename, extname } from "path";

// دمج أجزاء المسار
const fullPath = join(__dirname, "uploads", "image.jpg");

// الحصول على المسار المطلق
const absolutePath = resolve("./relative/path.txt");

// الحصول على مجلد الملف
const dir = dirname("/path/to/file.txt"); // "/path/to"

// الحصول على اسم الملف
const filename = basename("/path/to/file.txt"); // "file.txt"

// الحصول على امتداد الملف
const extension = extname("/path/to/file.txt"); // ".txt"

// sum.test.ts
import { test, expect } from "bun:test";

// الدالة المراد اختبارها
function sum(a: number, b: number): number {
return a + b;
}

// اختبار بسيط
test("إضافة 1 + 2 تساوي 3", () => {
expect(sum(1, 2)).toBe(3);
});

// اختبار متعدد التأكيدات
test("يجب أن تعمل الدالة مع أرقام مختلفة", () => {
expect(sum(1, 1)).toBe(2);
expect(sum(5, 7)).toBe(12);
expect(sum(-1, 1)).toBe(0);
expect(sum(0, 0)).toBe(0);
});

// اختبار للتحقق من رمي استثناء
test("يجب أن يفشل مع قيم غير صالحة", () => {
// @ts-ignore - اختبار متعمد لقيم خاطئة
expect(() => sum("a", 2)).toThrow();
});

# تشغيل جميع الاختبارات
bun test

# تشغيل ملف اختبار محدد
bun test sum.test.ts

# تشغيل الاختبارات بنمط معين
bun test --pattern "sum"

// async.test.ts
import { test, expect } from "bun:test";

// دالة غير متزامنة للاختبار
async function fetchData() {
return { success: true, data: [1, 2, 3] };
}

// اختبار غير متزامن
test("يجب أن تعيد بيانات بنجاح", async () => {
const result = await fetchData();

expect(result.success).toBe(true);
expect(result.data).toBeArray();
expect(result.data).toContain(2);
});

// math.test.ts
import { test, expect, describe } from "bun:test";

describe("اختبارات العمليات الحسابية", () => {
// اختبار الجمع
test("إضافة الأرقام", () => {
expect(1 + 2).toBe(3);
expect(5 + 5).toBe(10);
});

// اختبار الطرح
test("طرح الأرقام", () => {
expect(5 - 2).toBe(3);
expect(10 - 5).toBe(5);
});

// مجموعة فرعية من الاختبارات
describe("عمليات حسابية متقدمة", () => {
test("ضرب الأرقام", () => {
expect(2 * 3).toBe(6);
expect(4 * 5).toBe(20);
});

test("قسمة الأرقام", () => {
expect(10 / 2).toBe(5);
expect(20 / 4).toBe(5);
});
});
});

// hooks.test.ts
import { test, expect, beforeAll, afterAll, beforeEach, afterEach } from "bun:test";
import { createServer } from "./server";

let server;
let data = [];

// تنفيذ مرة واحدة قبل جميع الاختبارات
beforeAll(() => {
console.log("بدء تشغيل الاختبارات");
server = createServer();
});

// تنفيذ قبل كل اختبار
beforeEach(() => {
data = [1, 2, 3];
console.log("تجهيز البيانات للاختبار");
});

// تنفيذ بعد كل اختبار
afterEach(() => {
data = [];
console.log("تنظيف البيانات بعد الاختبار");
});

// تنفيذ مرة واحدة بعد جميع الاختبارات
afterAll(() => {
server.close();
console.log("انتهاء جميع الاختبارات");
});

test("اختبار البيانات", () => {
expect(data).toHaveLength(3);
data.push(4);
expect(data).toHaveLength(4);
});

test("اختبار البيانات مرة أخرى", () => {
// data سيكون [1, 2, 3] مرة أخرى بسبب beforeEach
expect(data).toHaveLength(3);
});

bun run app.ts

{
"compilerOptions": {
"target": "ES2021",
"module": "ESNext",
"moduleResolution": "node",
"types": ["bun-types"],
"esModuleInterop": true,
"strict": true,
"skipLibCheck": true,
"outDir": "dist"
},
"include": ["src/**/*"]
}

bun add -d bun-types

// app.ts
import { serve } from "bun";

// تعريف واجهة البيانات
interface User {
  id: number;
  name: string;
  email: string;
  isAdmin: boolean;
}

// إنشاء قائمة بالمستخدمين
const users: User[] = [
  { id: 1, name: "أحمد", email: "[email protected]", isAdmin: true },
  { id: 2, name: "سارة", email: "[email protected]", isAdmin: false },
  { id: 3, name: "محمد", email: "[email protected]", isAdmin: false }
];

// إنشاء خادم HTTP
const server = serve({
  port: 3000,
  fetch(req): Response {
    const url = new URL(req.url);
    
    // إرجاع جميع المستخدمين
    if (url.pathname === "/api/users") {
      return Response.json(users);
    }
    
    // إرجاع مستخدم حسب المعرف
    if (url.pathname.startsWith("/api/users/")) {
      const id = parseInt(url.pathname.split("/").pop() || "0");
      const user = users.find(u => u.id === id);
      
      if (!user) {
        return new Response("لم يتم العثور على المستخدم", { status: 404 });
      }
      
      return Response.json(user);
    }
    
    return new Response("مرحبًا بك في واجهة برمجة التطبيقات!");
  }
});

console.log(`الخادم يعمل على المنفذ ${server.port}`);

bun run app.jsx
bun run app.tsx

[jsx]
runtime = "automatic" # أو "classic"
pragma = "h" # لـ Preact
fragmentPragma = "Fragment"

// app.jsx
import { serve } from "bun";
import React from "react";
import { renderToString } from "react-dom/server";

// مكون React بسيط
const App = ({ name }) => {
  return (
    
      
        
      
      
        

          
مرحبًا بك في Bun.js!
          
مرحبًا يا {name}
        
      
    
  );
};

// إنشاء خادم HTTP
serve({
  port: 3000,
  fetch(req) {
    return new Response(
      renderToString(),
      {
        headers: {
          "Content-Type": "text/html; charset=utf-8",
        },
      }
    );
  }
});

bun create react my-react-app

cd my-react-app
bun dev

# .env
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/mydb
API_KEY=your_secret_api_key
DEBUG=false

// الطريقة الأولى: استخدام process.env (متوافق مع Node.js)
const port = process.env.PORT || 3000;
console.log(`المنفذ: ${port}`);

// الطريقة الثانية: استخدام Bun.env (خاص ببن)
const apiKey = Bun.env.API_KEY;
console.log(`مفتاح واجهة البرمجة: ${apiKey}`);

import { config } from "bun";

// تحميل ملف .env محدد
config({ path: "./config/.env.test" });

PORT=4000 DEBUG=true bun run server.ts

import { Database } from "bun:sqlite";

// إنشاء أو فتح قاعدة بيانات
const db = new Database("mydata.sqlite");

// إنشاء جدول
db.run(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  )
`);

// إضافة بيانات
const insertUser = db.prepare(`
  INSERT INTO users (name, email) VALUES ($name, $email)
`);

insertUser.run({
  $name: "أحمد",
  $email: "[email protected]"
});

// قراءة البيانات
const users = db.query("SELECT * FROM users").all();
console.log(users);

// استخدام استعلام معد مسبقًا مع معلمات
const getUserById = db.prepare("SELECT * FROM users WHERE id = $id");
const user = getUserById.get({ $id: 1 });
console.log(user);

// إغلاق قاعدة البيانات (اختياري)
db.close();

// مثال لاستخدام PostgreSQL مع Bun.js
import postgres from "postgres";

// إنشاء اتصال
const sql = postgres("postgres://username:password@localhost:5432/database");

// استعلام بسيط
const users = await sql`SELECT * FROM users`;
console.log(users);

// إضافة سجل
const newUser = await sql`
  INSERT INTO users (name, email)
  VALUES (${"محمد"}, ${"[email protected]"})
  RETURNING *
`;

// إغلاق الاتصال عند الانتهاء
await sql.end();

// مثال لاستخدام MongoDB مع Bun.js
import { MongoClient } from "mongodb";

// إنشاء اتصال
const client = new MongoClient("mongodb://localhost:27017");
await client.connect();

// الوصول إلى قاعدة البيانات والمجموعة
const db = client.db("myapp");
const users = db.collection("users");

// إضافة بيانات
await users.insertOne({
  name: "سارة",
  email: "[email protected]",
  age: 28,
  createdAt: new Date()
});

// قراءة البيانات
const allUsers = await users.find({}).toArray();
console.log(allUsers);

// إغلاق الاتصال
await client.close();

// استخدام FFI للوظائف كثيفة الحوسبة
import { dlopen, FFIType } from "bun:ffi";

// تحميل مكتبة C مثلاً للوظائف كثيفة الحوسبة
const lib = dlopen("./libcalculator.so", {
  calculate: {
    args: [FFIType.i32, FFIType.i32],
    returns: FFIType.i32
  }
});

// استدعاء الدالة المكتوبة بلغة C
const result = lib.symbols.calculate(10, 20);
console.log(result);

// استخدام التخزين المؤقت للطلبات المتكررة
import { serve } from "bun";

// إنشاء خريطة للتخزين المؤقت
const responseCache = new Map();

serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
    const cacheKey = url.pathname + url.search;
    
    // التحقق من التخزين المؤقت
    if (responseCache.has(cacheKey)) {
      return responseCache.get(cacheKey);
    }
    
    // إنشاء استجابة جديدة
    const response = new Response(`مرحبًا! الوقت الحالي: ${new Date().toISOString()}`);
    
    // تخزين الاستجابة في التخزين المؤقت (لمدة معينة)
    responseCache.set(cacheKey, response);
    setTimeout(() => responseCache.delete(cacheKey), 10000); // حذف بعد 10 ثوانٍ
    
    return response;
  }
});

// استخدام Bun.spawn لتشغيل عمليات متوازية
import { spawn } from "bun";

async function runParallelTasks() {
  const processes = [];
  
  // تشغيل 3 عمليات متوازية
  for (let i = 0; i < 3; i++) {
    processes.push(
      spawn({
        cmd: ["bun", "run", "worker.ts", i.toString()],
        stdout: "pipe",
        env: { WORKER_ID: i.toString() }
      })
    );
  }
  
  // انتظار انتهاء جميع العمليات
  for (const proc of processes) {
    const text = await new Response(proc.stdout).text();
    console.log(`نتيجة العملية: ${text}`);
  }
}

runParallelTasks();