Effect-TS: معالجة الأخطاء المُنمَّطة والخدمات والأنابيب لتطبيقات TypeScript الإنتاجية

// النهج التقليدي — الأخطاء غير مرئية لنظام الأنواع
async function getUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) throw new Error("Failed to fetch user");
  return response.json();
}
 
// ما الأخطاء التي يمكن أن تُرمى؟ توقيع النوع لا يخبرك.
// قد تكون: NetworkError, NotFoundError, ParseError, TimeoutError...

import { Effect } from "effect";
 
// Effect<User, NetworkError | NotFoundError, UserService>
//  نوع النجاح ↑    أنواع الأخطاء ↑              التبعيات ↑

mkdir effect-user-service && cd effect-user-service
npm init -y
npm install effect @effect/platform @effect/schema
npm install -D typescript tsx @types/node

npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

mkdir -p src/{errors,services,layers,models}

{
  "scripts": {
    "dev": "tsx watch src/main.ts",
    "start": "tsx src/main.ts"
  }
}

//  Effect<Success, Error, Requirements>
//
//  Success      — القيمة المُنتَجة عند النجاح
//  Error        — أنواع الأخطاء المحتملة (اتحاد)
//  Requirements — الخدمات/التبعيات المطلوبة للتشغيل

import { Effect, Console } from "effect";
 
// Effect بسيط ينجح بسلسلة نصية
const greeting = Effect.succeed("Hello, Effect!");
 
// Effect بسيط يفشل بخطأ
const failure = Effect.fail("Something went wrong");
 
// Effects كسولة — لا شيء يعمل حتى تنفّذها
// هذا مجرد وصف لعملية حسابية
 
// تحويل القيم باستخدام map
const loudGreeting = greeting.pipe(
  Effect.map((msg) => msg.toUpperCase())
);
 
// ربط effects باستخدام flatMap
const program = Effect.flatMap(greeting, (msg) => {
  return Console.log(msg);
});
 
// استخدم المولّدات لأسلوب حتمي (مُوصى به)
const generatorProgram = Effect.gen(function* () {
  const msg = yield* greeting;
  yield* Console.log(msg);
  yield* Console.log("Effect-TS is awesome!");
});
 
// شغّل البرنامج
Effect.runPromise(generatorProgram).then(() => {
  console.log("Done!");
});

npx tsx src/basics.ts

import { Data } from "effect";
 
// Data.TaggedError ينشئ عضو اتحاد مُوسَم بحقل _tag
// هذا يُمكّن المطابقة الشاملة للأنماط
 
export class UserNotFoundError extends Data.TaggedError(
  "UserNotFoundError"
)<{
  readonly userId: string;
}> {}
 
export class UserAlreadyExistsError extends Data.TaggedError(
  "UserAlreadyExistsError"
)<{
  readonly email: string;
}> {}
 
export class ValidationError extends Data.TaggedError(
  "ValidationError"
)<{
  readonly field: string;
  readonly message: string;
}> {}
 
export class DatabaseError extends Data.TaggedError(
  "DatabaseError"
)<{
  readonly operation: string;
  readonly cause: unknown;
}> {}
 
export class NetworkError extends Data.TaggedError(
  "NetworkError"
)<{
  readonly url: string;
  readonly statusCode: number;
}> {}

import { Effect } from "effect";
import { UserNotFoundError, ValidationError } from "./errors/user-errors.js";
 
// نوع الإرجاع يعلن صراحةً: يمكن أن يفشل بـ
// UserNotFoundError أو ValidationError
function getUser(
  id: string
): Effect.Effect<User, UserNotFoundError | ValidationError> {
  return Effect.gen(function* () {
    if (!id || id.length === 0) {
      return yield* new ValidationError({
        field: "id",
        message: "User ID cannot be empty",
      });
    }
 
    const user = yield* lookupUser(id);
 
    if (!user) {
      return yield* new UserNotFoundError({ userId: id });
    }
 
    return user;
  });
}

import { Schema } from "@effect/schema";
 
// تعريف مخطط المستخدم — يتحقق في وقت التشغيل، يستنتج الأنواع في وقت التجميع
export const UserSchema = Schema.Struct({
  id: Schema.String.pipe(Schema.nonEmptyString()),
  email: Schema.String.pipe(Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)),
  name: Schema.String.pipe(Schema.nonEmptyString(), Schema.maxLength(100)),
  role: Schema.Literal("admin", "user", "moderator"),
  createdAt: Schema.Date,
  updatedAt: Schema.Date,
});
 
// استنتاج نوع TypeScript من المخطط
export type User = typeof UserSchema.Type;
 
// مخطط لإنشاء مستخدم جديد (بدون id، التواريخ تُولَّد تلقائياً)
export const CreateUserSchema = Schema.Struct({
  email: Schema.String.pipe(Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)),
  name: Schema.String.pipe(Schema.nonEmptyString(), Schema.maxLength(100)),
  role: Schema.optional(Schema.Literal("admin", "user", "moderator"), {
    default: () => "user" as const,
  }),
});
 
export type CreateUser = typeof CreateUserSchema.Type;
 
// مخطط لتحديث مستخدم موجود
export const UpdateUserSchema = Schema.Struct({
  email: Schema.optional(
    Schema.String.pipe(Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/))
  ),
  name: Schema.optional(
    Schema.String.pipe(Schema.nonEmptyString(), Schema.maxLength(100))
  ),
  role: Schema.optional(Schema.Literal("admin", "user", "moderator")),
});
 
export type UpdateUser = typeof UpdateUserSchema.Type;

import { Effect, Context, Layer } from "effect";
import type { User, CreateUser, UpdateUser } from "../models/user.js";
import {
  UserNotFoundError,
  UserAlreadyExistsError,
  DatabaseError,
} from "../errors/user-errors.js";
 
// 1. تعريف واجهة الخدمة باستخدام Context.Tag
export class UserRepository extends Context.Tag("UserRepository")<
  UserRepository,
  {
    readonly findById: (
      id: string
    ) => Effect.Effect<User, UserNotFoundError | DatabaseError>;
 
    readonly findByEmail: (
      email: string
    ) => Effect.Effect<User | null, DatabaseError>;
 
    readonly create: (
      data: CreateUser
    ) => Effect.Effect<User, UserAlreadyExistsError | DatabaseError>;
 
    readonly update: (
      id: string,
      data: UpdateUser
    ) => Effect.Effect<User, UserNotFoundError | DatabaseError>;
 
    readonly delete: (
      id: string
    ) => Effect.Effect<void, UserNotFoundError | DatabaseError>;
 
    readonly list: () => Effect.Effect<ReadonlyArray<User>, DatabaseError>;
  }
>() {}

import { Effect, Layer, Ref } from "effect";
import { UserRepository } from "../services/user-repository.js";
import type { User, CreateUser, UpdateUser } from "../models/user.js";
import {
  UserNotFoundError,
  UserAlreadyExistsError,
  DatabaseError,
} from "../errors/user-errors.js";
 
export const InMemoryUserRepository = Layer.effect(
  UserRepository,
  Effect.gen(function* () {
    const store = yield* Ref.make<Map<string, User>>(new Map());
    let counter = 0;
 
    return {
      findById: (id: string) =>
        Effect.gen(function* () {
          const users = yield* Ref.get(store);
          const user = users.get(id);
          if (!user) {
            return yield* new UserNotFoundError({ userId: id });
          }
          return user;
        }),
 
      findByEmail: (email: string) =>
        Effect.gen(function* () {
          const users = yield* Ref.get(store);
          for (const user of users.values()) {
            if (user.email === email) return user;
          }
          return null;
        }),
 
      create: (data: CreateUser) =>
        Effect.gen(function* () {
          const existing = yield* Effect.flatMap(
            Ref.get(store),
            (users) => {
              for (const user of users.values()) {
                if (user.email === data.email) {
                  return Effect.succeed(user);
                }
              }
              return Effect.succeed(null);
            }
          );
 
          if (existing) {
            return yield* new UserAlreadyExistsError({
              email: data.email,
            });
          }
 
          counter++;
          const now = new Date();
          const user: User = {
            id: `user_${counter}`,
            email: data.email,
            name: data.name,
            role: data.role ?? "user",
            createdAt: now,
            updatedAt: now,
          };
 
          yield* Ref.update(store, (map) => {
            const next = new Map(map);
            next.set(user.id, user);
            return next;
          });
 
          return user;
        }),
 
      update: (id: string, data: UpdateUser) =>
        Effect.gen(function* () {
          const users = yield* Ref.get(store);
          const existing = users.get(id);
          if (!existing) {
            return yield* new UserNotFoundError({ userId: id });
          }
 
          const updated: User = {
            ...existing,
            ...Object.fromEntries(
              Object.entries(data).filter(([, v]) => v !== undefined)
            ),
            updatedAt: new Date(),
          };
 
          yield* Ref.update(store, (map) => {
            const next = new Map(map);
            next.set(id, updated);
            return next;
          });
 
          return updated;
        }),
 
      delete: (id: string) =>
        Effect.gen(function* () {
          const users = yield* Ref.get(store);
          if (!users.has(id)) {
            return yield* new UserNotFoundError({ userId: id });
          }
          yield* Ref.update(store, (map) => {
            const next = new Map(map);
            next.delete(id);
            return next;
          });
        }),
 
      list: () =>
        Effect.gen(function* () {
          const users = yield* Ref.get(store);
          return Array.from(users.values());
        }),
    };
  })
);

import { Effect, Context, Layer } from "effect";
import { Schema } from "@effect/schema";
import { UserRepository } from "./user-repository.js";
import {
  CreateUserSchema,
  UpdateUserSchema,
  type User,
} from "../models/user.js";
import {
  UserNotFoundError,
  UserAlreadyExistsError,
  ValidationError,
  DatabaseError,
} from "../errors/user-errors.js";
 
export class UserService extends Context.Tag("UserService")<
  UserService,
  {
    readonly getUser: (
      id: string
    ) => Effect.Effect<User, UserNotFoundError | DatabaseError>;
 
    readonly createUser: (
      input: unknown
    ) => Effect.Effect<
      User,
      ValidationError | UserAlreadyExistsError | DatabaseError
    >;
 
    readonly updateUser: (
      id: string,
      input: unknown
    ) => Effect.Effect<
      User,
      ValidationError | UserNotFoundError | DatabaseError
    >;
 
    readonly deleteUser: (
      id: string
    ) => Effect.Effect<void, UserNotFoundError | DatabaseError>;
 
    readonly listUsers: () => Effect.Effect<
      ReadonlyArray<User>,
      DatabaseError
    >;
  }
>() {}
 
export const UserServiceLive = Layer.effect(
  UserService,
  Effect.gen(function* () {
    const repo = yield* UserRepository;
 
    return {
      getUser: (id: string) => repo.findById(id),
 
      createUser: (input: unknown) =>
        Effect.gen(function* () {
          const parsed = yield* Schema.decodeUnknown(
            CreateUserSchema
          )(input).pipe(
            Effect.mapError(
              (error) =>
                new ValidationError({
                  field: "input",
                  message: `Invalid input: ${error.message}`,
                })
            )
          );
 
          const existing = yield* repo.findByEmail(parsed.email);
          if (existing) {
            return yield* new UserAlreadyExistsError({
              email: parsed.email,
            });
          }
 
          return yield* repo.create(parsed);
        }),
 
      updateUser: (id: string, input: unknown) =>
        Effect.gen(function* () {
          const parsed = yield* Schema.decodeUnknown(
            UpdateUserSchema
          )(input).pipe(
            Effect.mapError(
              (error) =>
                new ValidationError({
                  field: "input",
                  message: `Invalid input: ${error.message}`,
                })
            )
          );
 
          yield* repo.findById(id);
          return yield* repo.update(id, parsed);
        }),
 
      deleteUser: (id: string) => repo.delete(id),
      listUsers: () => repo.list(),
    };
  })
);

import { Effect, Match } from "effect";
import { UserService } from "./services/user-service.js";
 
// النمط 1: التقاط أخطاء محددة
const getUserSafe = (id: string) =>
  Effect.gen(function* () {
    const service = yield* UserService;
    return yield* service.getUser(id).pipe(
      Effect.catchTag("UserNotFoundError", () =>
        Effect.succeed(null)
      )
    );
  });
 
// النمط 2: مطابقة شاملة للأخطاء
const createUserWithHandling = (input: unknown) =>
  Effect.gen(function* () {
    const service = yield* UserService;
    return yield* service.createUser(input).pipe(
      Effect.catchAll((error) =>
        Match.value(error).pipe(
          Match.tag("ValidationError", (e) =>
            Effect.succeed({ status: 400 as const, message: e.message })
          ),
          Match.tag("UserAlreadyExistsError", (e) =>
            Effect.succeed({ status: 409 as const, message: `${e.email} موجود` })
          ),
          Match.tag("DatabaseError", (e) =>
            Effect.succeed({ status: 500 as const, message: `خطأ قاعدة بيانات: ${e.operation}` })
          ),
          Match.exhaustive
        )
      )
    );
  });
 
// النمط 3: إعادة المحاولة مع تراجع
const getUserWithRetry = (id: string) =>
  Effect.gen(function* () {
    const service = yield* UserService;
    return yield* service.getUser(id).pipe(
      Effect.retry({
        times: 3,
        schedule: "exponential",
        while: (error) => error._tag === "DatabaseError",
      })
    );
  });

import { Effect, pipe, Array as Arr } from "effect";
import { UserService } from "./services/user-service.js";
 
const processUsers = Effect.gen(function* () {
  const service = yield* UserService;
  const users = yield* service.listUsers();
 
  const processed = pipe(
    users,
    Arr.filter((user) => user.role === "admin"),
    Arr.map((user) => ({
      id: user.id,
      displayName: user.name.toUpperCase(),
      email: user.email,
    })),
    Arr.sort((a, b) => a.displayName.localeCompare(b.displayName))
  );
 
  return processed;
});
 
// تشغيل عدة effects بالتوازي
const fetchMultipleUsers = (ids: string[]) =>
  Effect.gen(function* () {
    const service = yield* UserService;
    const users = yield* Effect.all(
      ids.map((id) => service.getUser(id)),
      { concurrency: 5 }
    );
    return users;
  });

import { Effect, Console, Layer } from "effect";
import { UserService, UserServiceLive } from "./services/user-service.js";
import { InMemoryUserRepository } from "./layers/in-memory-user-repository.js";
 
const program = Effect.gen(function* () {
  const service = yield* UserService;
 
  yield* Console.log("=== Effect-TS User Management ===\n");
 
  const alice = yield* service.createUser({
    name: "Alice Johnson",
    email: "alice@example.com",
    role: "admin",
  });
  yield* Console.log(`Created: ${alice.name} (${alice.id})`);
 
  const bob = yield* service.createUser({
    name: "Bob Smith",
    email: "bob@example.com",
  });
  yield* Console.log(`Created: ${bob.name} (${bob.id})`);
 
  // محاولة إنشاء مكرر
  yield* service.createUser({
    name: "Alice Clone",
    email: "alice@example.com",
  }).pipe(
    Effect.catchTag("UserAlreadyExistsError", (e) =>
      Console.log(`تم منع التكرار: ${e.email} موجود بالفعل`)
    )
  );
 
  const allUsers = yield* service.listUsers();
  yield* Console.log(`\nإجمالي المستخدمين: ${allUsers.length}`);
});
 
// ربط الطبقات — هنا يحدث حقن التبعيات
const MainLayer = UserServiceLive.pipe(
  Layer.provide(InMemoryUserRepository)
);
 
const runnable = program.pipe(Effect.provide(MainLayer));
 
Effect.runPromise(runnable).then(() => {
  console.log("\n✓ اكتمل البرنامج بنجاح");
});

npm start

import { Effect, Layer } from "effect";
import { UserService, UserServiceLive } from "./services/user-service.js";
import { UserRepository } from "./services/user-repository.js";
import { DatabaseError } from "./errors/user-errors.js";
 
// إنشاء مستودع اختبار يحاكي الفشل
const FailingRepository = Layer.succeed(UserRepository, {
  findById: (id: string) =>
    new DatabaseError({ operation: "findById", cause: "Connection refused" }),
  findByEmail: () => Effect.succeed(null),
  create: () =>
    new DatabaseError({ operation: "create", cause: "Disk full" }),
  update: () =>
    new DatabaseError({ operation: "update", cause: "Timeout" }),
  delete: () =>
    new DatabaseError({ operation: "delete", cause: "Permission denied" }),
  list: () => Effect.succeed([]),
});
 
const testDatabaseFailure = Effect.gen(function* () {
  const service = yield* UserService;
  const result = yield* service.getUser("user_1").pipe(
    Effect.matchEffect({
      onSuccess: () => Effect.succeed("FAIL: should have errored"),
      onFailure: (error) => {
        if (error._tag === "DatabaseError") {
          return Effect.succeed(`PASS: Got DatabaseError for ${error.operation}`);
        }
        return Effect.succeed(`FAIL: Wrong error type: ${error._tag}`);
      },
    })
  );
  console.log(result);
});
 
const TestLayer = UserServiceLive.pipe(Layer.provide(FailingRepository));
 
Effect.runPromise(
  testDatabaseFailure.pipe(Effect.provide(TestLayer))
);

import { Effect, Duration } from "effect";
 
const getUserWithTimeout = (id: string) =>
  Effect.gen(function* () {
    const service = yield* UserService;
    return yield* service.getUser(id);
  }).pipe(
    Effect.timeout(Duration.seconds(5))
  );

import { Effect } from "effect";
 
const withDatabaseConnection = Effect.acquireRelease(
  Effect.sync(() => {
    console.log("Opening database connection");
    return { connectionId: Math.random().toString(36) };
  }),
  (connection) =>
    Effect.sync(() => {
      console.log(`Closing connection ${connection.connectionId}`);
    })
);
 
const queryWithConnection = Effect.scoped(
  Effect.gen(function* () {
    const conn = yield* withDatabaseConnection;
    console.log(`Using connection: ${conn.connectionId}`);
    return "query result";
  })
);

// خطأ
const user = service.getUser(id);
 
// صحيح
const user = yield* service.getUser(id);