TypeScript'te Builder Pattern: Modern Uygulamalarda Tip Güvenli Konfigürasyon

Özet

TypeScript’teki Builder pattern, geleneksel nesne yönelimli dillerdekinden farklı bir amaca hizmet eder. Java ve C# builder’ları çok sayıda opsiyonel parametreyi yönetmek için kullanırken, TypeScript implementasyonu generic’ler ve conditional type’ları kullanarak karmaşık kısıtlamaları compile time’da zorunlu kılar ve potansiyel runtime hatalarını IDE’nin yakalayabileceği tip hatalarına dönüştürür. Bu rehber, serverless altyapı, veritabanı katmanı, API konfigürasyonu ve test alanlarında pratik uygulamaları ele alarak, builder’ların production’a ulaşmadan önce yanlış konfigürasyonları nasıl önlediğini gösteriyor.

TypeScript’te Karmaşık Nesnelerin Sorunu

TypeScript projelerinde tekrar eden bir pattern ortaya çıkar: sistemler büyüdükçe, konfigürasyon nesnelerinin karmaşıklığı da artar. 3-4 parametreli basit bir Lambda fonksiyonu olarak başlayan şey, 20+ konfigürasyon seçeneği olan bir canavara dönüşür: VPC ayarları, environment variable’lar, IAM rolleri, layer’lar, timeout değerleri, memory allocation ve daha fazlası.

AWS CDK kullanarak tipik bir AWS Lambda konfigürasyonu:

new lambda.Function(this, 'ApiHandler', {
  runtime: lambda.Runtime.NODEJS_20_X,
  handler: 'index.handler',
  code: lambda.Code.fromAsset('lambda'),
  timeout: Duration.seconds(30),
  memorySize: 1024,
  environment: {
    TABLE_NAME: table.tableName,
    API_KEY: apiKey.secretValue
  },
  layers: [commonLayer, vendorLayer],
  vpc: vpc,
  vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
  securityGroups: [lambdaSecurityGroup],
  deadLetterQueue: dlq,
  retryAttempts: 2,
  reservedConcurrentExecutions: 10,
  tracing: lambda.Tracing.ACTIVE,
  logRetention: logs.RetentionDays.ONE_WEEK,
  // ... ve daha fazlası
});

Sorunlar hızla birikiyor:

1. Konfigürasyon cehennemi: Parametreler sıraya bağımlı ve yanlış yerleştirmesi kolay
2. Rehberlik yok: Hangi parametreler zorunlu? Neye ne bağlı?
3. Runtime sürprizleri: Birçok konfigürasyon hatası ancak Lambda çalıştığında ortaya çıkıyor
4. Tekrar: Multi-region deployment’lar bu bloğun tamamını kopyalayıp değiştirmeyi gerektiriyor

TypeScript’in opsiyonel parametreleri biraz yardımcı oluyor, ama “VPC’yi etkinleştirirsen subnet’leri sağlamalısın” veya “dead letter queue, permission konfigürasyonu gerektirir” gibi kuralları ifade edemiyorlar. Fluent builder API’si bu bağımlılıkları method chain’inde zorunlu kılar. Bu tür bağımlılıklar genellikle runtime’da keşfedilir ve pahalıya mal olur.

Serverless API’lerde bunlar sadece kolaylık sorunları değil, deployment riskleridir. Bir Lambda görünüşte iyi olabilir ama runtime’da VPC konfigürasyonu eksik olduğu için başarısız olabilir. TypeScript derleyicisi yardımcı olamaz çünkü teknik olarak tüm tipler doğrudur. Builder pattern bu tür hataları derleme aşamasına taşıyor: örn. VPC + subnet bağımlılığı gibi kurallar fluent API ile compile-time’a kodlanabilir.

TypeScript Builder’larını Farklı Kılan Şey

TypeScript’in tip sistemi, Builder pattern’e temel olarak farklı bir yaklaşımı mümkün kılıyor. Sadece daha temiz bir API sağlamanın ötesinde (bunu da yapıyor tabii), TypeScript builder’ları iş kurallarını doğrudan tiplere kodlayabilir ve geçersiz durumları temsil edilemez hale getirebilir.

İşte kavramsal fark:

Ana fikir: builder’lar konfigürasyon durumunu generic tip parametreleri aracılığıyla takip eder. Her method çağrısı neyin konfigüre edildiğini yansıtan yeni bir tip döndürür ve build() metodu ancak tüm zorunlu konfigürasyon tamamlandığında kullanılabilir hale gelir.

Progressive tip güvenliğini gösteren basit bir örnek:

type RequiredFields = 'url' | 'method';

class HttpRequestBuilder<TSet extends string = never> {
  private config: Partial<HttpRequest> = {};

  withUrl(url: string): HttpRequestBuilder<TSet | 'url'> {
    this.config.url = url;
    return this as any;
  }

  withMethod(method: string): HttpRequestBuilder<TSet | 'method'> {
    this.config.method = method;
    return this as any;
  }

  withHeaders(headers: Record<string, string>): this {
    this.config.headers = headers;
    return this;
  }

  // build() sadece zorunlu alanlar ayarlandığında kullanılabilir
  build(this: HttpRequestBuilder<RequiredFields>): HttpRequest {
    return this.config as HttpRequest;
  }
}

// Kullanım
const request = new HttpRequestBuilder()
  .withHeaders({ 'Content-Type': 'application/json' })
  .build(); // Bad: Derleme hatası: 'url' ve 'method' ayarlanmamış

const validRequest = new HttpRequestBuilder()
  .withUrl('https://api.example.com/users')
  .withMethod('GET')
  .withHeaders({ 'Content-Type': 'application/json' })
  .build(); // Good: Başarıyla derlenir

Bu compile-time zorunluluğu, TypeScript builder’larını diğer dillerdeki eşdeğerlerinden ayıran şeydir. Sadece API’yi daha uygun hale getirmiyorsun - belirli bug sınıflarını imkansız kılıyorsun.

Temel İmplementasyon: Tip Güvenli Lambda Builder

İşte bunun daha önceki Lambda problemine nasıl uygulandığı: düzgün konfigürasyonu zorunlu kılan bir builder:

import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import { Duration } from 'aws-cdk-lib';

interface LambdaConfig {
  runtime: lambda.Runtime;
  handler: string;
  code: lambda.Code;
  timeout?: Duration;
  memorySize?: number;
  environment?: Record<string, string>;
  vpc?: ec2.IVpc;
  vpcSubnets?: ec2.SubnetSelection;
}

class LambdaFunctionBuilder {
  private config: Partial<LambdaConfig> = {
    timeout: Duration.seconds(30),
    memorySize: 1024,
  };

  withRuntime(runtime: lambda.Runtime): this {
    this.config.runtime = runtime;
    return this;
  }

  withHandler(handler: string): this {
    this.config.handler = handler;
    return this;
  }

  fromAssetCode(path: string): this {
    this.config.code = lambda.Code.fromAsset(path);
    return this;
  }

  withTimeout(seconds: number): this {
    if (seconds <= 0 || seconds > 900) {
      throw new Error('Timeout 1 ile 900 saniye arasında olmalı');
    }
    this.config.timeout = Duration.seconds(seconds);
    return this;
  }

  withMemory(mb: number): this {
    const validSizes = [128, 256, 512, 1024, 2048, 4096, 8192, 10240];
    if (!validSizes.includes(mb)) {
      throw new Error(`Memory şunlardan biri olmalı: ${validSizes.join(', ')}`);
    }
    this.config.memorySize = mb;
    return this;
  }

  withEnvironment(vars: Record<string, string>): this {
    this.config.environment = {
      ...this.config.environment,
      ...vars
    };
    return this;
  }

  inVpc(vpc: ec2.IVpc, subnetType: ec2.SubnetType = ec2.SubnetType.PRIVATE_WITH_EGRESS): this {
    this.config.vpc = vpc;
    this.config.vpcSubnets = { subnetType };
    return this;
  }

  build(): lambda.FunctionProps {
    if (!this.config.runtime || !this.config.handler || !this.config.code) {
      throw new Error('Runtime, handler ve code zorunludur');
    }

    return this.config as lambda.FunctionProps;
  }
}

// Kullanım: Temiz, kendini dokümante eden ve tip güvenli
const lambdaProps = new LambdaFunctionBuilder()
  .withRuntime(lambda.Runtime.NODEJS_20_X)
  .withHandler('index.handler')
  .fromAssetCode('lambda')
  .withTimeout(60)
  .withMemory(2048)
  .withEnvironment({
    TABLE_NAME: table.tableName,
    LOG_LEVEL: 'info'
  })
  .inVpc(vpc)
  .build();

const apiFunction = new lambda.Function(this, 'ApiHandler', lambdaProps);

İyileştirmelere dikkat et:

• Erken validasyon: Geçersiz timeout veya memory değerleri deployment’ta değil hemen yakalanıyor
• Net varsayılanlar: Yaygın konfigürasyonlar (30s timeout, 1024MB memory) otomatik ayarlanıyor
• Okunabilir: Fluent interface neredeyse dokümantasyon gibi okunuyor
• Yeniden kullanılabilir: Temel konfigürasyonlar oluşturup spesifik kullanım durumları için genişletebilirsin

Bu pattern, birden fazla region’da düzinelerce Lambda fonksiyonunu yönetirken daha da güçlü hale geliyor. Region’a özgü VPC ve security group farklarını kapsülleyen builder’lar oluşturabilirsin.

Gerçek Dünya Uygulaması: Multi-Region Serverless API

Multi-region serverless mimaride karmaşıklığı yönetmek için builder’lar şöyle kullanılır:

// Tüm region'larda paylaşılan temel konfigürasyon
const baseBuilder = new LambdaFunctionBuilder()
  .withRuntime(lambda.Runtime.NODEJS_20_X)
  .withHandler('index.handler')
  .fromAssetCode('lambda')
  .withTimeout(30)
  .withEnvironment({
    LOG_LEVEL: 'info',
    POWERTOOLS_SERVICE_NAME: 'api'
  });

// Region'a özgü konfigürasyonlar
const usEastFunction = new lambda.Function(this, 'UsEastApi',
  baseBuilder
    .withEnvironment({ REGION: 'us-east-1' })
    .inVpc(usEastVpc)
    .build()
);

const euWestFunction = new lambda.Function(this, 'EuWestApi',
  baseBuilder
    .withEnvironment({ REGION: 'eu-west-1' })
    .inVpc(euWestVpc)
    .build()
);

Bu yaklaşım CDK kodunu yaklaşık %40 azaltırken, regional farkları açık ve kolayca fark edilebilir hale getirir. Yeni bir region eklendiğinde, tam olarak neyin farklı konfigüre edilmesi gerektiği açıktır.

Database Query Builder’lar: Şemadan Sonuçlara Tip Güvenliği

Query builder’lar muhtemelen TypeScript’te Builder pattern’in en ikna edici kullanım durumunu temsil ediyor. Kysely gibi kütüphaneler, builder’ların veritabanı şemasından sorgu sonuçlarına kadar uçtan uca tip güvenliği nasıl sağlayabileceğini gösteriyor.

İşte tip güvenliği akışı:

Tip güvenli query builder pattern kullanan pratik bir örnek:

interface Database {
  users: {
    id: string;
    email: string;
    name: string;
    role: 'admin' | 'user';
    createdAt: Date;
  };
  posts: {
    id: string;
    authorId: string;
    title: string;
    content: string;
    publishedAt: Date | null;
  };
}

class QueryBuilder<TTable extends keyof Database, TResult = Database[TTable]> {
  constructor(
    private table: TTable,
    private query: Partial<{
      select: (keyof Database[TTable])[];
      where: Partial<Database[TTable]>;
      limit: number;
    }> = {}
  ) {}

  select<K extends keyof Database[TTable]>(
    ...columns: K[]
  ): QueryBuilder<TTable, Pick<Database[TTable], K>> {
    return new QueryBuilder(this.table, {
      ...this.query,
      select: columns as any
    });
  }

  where(conditions: Partial<Database[TTable]>): this {
    this.query.where = { ...this.query.where, ...conditions };
    return this;
  }

  limit(count: number): this {
    this.query.limit = count;
    return this;
  }

  async execute(): Promise<TResult[]> {
    // Gerçek implementasyonda bu sorguyu çalıştırır
    // Burada sadece tip güvenliğini gösteriyoruz
    console.log(`${this.table} üzerinde sorgu çalıştırılıyor:`, this.query);
    return [] as TResult[];
  }
}

// Temiz API için factory fonksiyonu
function from<T extends keyof Database>(table: T) {
  return new QueryBuilder(table);
}

// Tam tip güvenliği ile kullanım
const users = await from('users')
  .select('id', 'email', 'name')  // Good: Otomatik tamamlama çalışıyor
  .where({ role: 'admin' })  // Good: Sadece geçerli alanlar izin veriliyor
  .limit(10)
  .execute();
// users'ın tipi: Array<{ id: string, email: string, name: string }>

const posts = await from('posts')
  .select('title', 'publishedAt')
  .where({ authorId: 'user-123' })
  .execute();
// posts'un tipi: Array<{ title: string, publishedAt: Date | null }>

// Bad: Bu derlenmez - 'invalid' bir sütun değil
// const invalid = await from('users').select('invalid').execute();

// Bad: Bu derlenmez - 'posts' tablosunda 'email' yok
// const invalidWhere = await from('posts').where({ email: '[email protected]' }).execute();

Buradaki güç, yazım hatalarının ve yanlış sütun referanslarının compile time’da yakalanması, production’da sorgunun başarısız olmasında değil. Bu yaklaşım code review’dan kaçabilecek düzinelerce bug’ı yakalar.

API Konfigürasyonu: Express Middleware Builder’lar

Express veya Fastify’daki middleware chain’leri, sıranın önemli olduğu ve hataların maliyetli olduğu başka bir alan. Authentication, authorization’dan önce gelmeli, logging request ID’leri içermeli ve error handler’lar en sonda olmalı.

Bu kuralları kodlayan bir builder:

import { RequestHandler, ErrorRequestHandler, Router } from 'express';

class RouterBuilder {
  private middlewares: RequestHandler[] = [];
  private errorHandlers: ErrorRequestHandler[] = [];
  private router = Router();
  private hasAuth = false;

  withRequestId(): this {
    this.middlewares.push((req, res, next) => {
      res.locals.requestId = crypto.randomUUID();
      next();
    });
    return this;
  }

  withLogging(): this {
    this.middlewares.push((req, res, next) => {
      console.log(`${res.locals.requestId} ${req.method} ${req.path}`);
      next();
    });
    return this;
  }

  withRateLimiting(options: { requestsPerMinute: number }): this {
    // Rate limiting implementasyonu
    this.middlewares.push((req, res, next) => {
      // Rate limit kontrolü
      next();
    });
    return this;
  }

  withAuth(validator: RequestHandler): this {
    this.hasAuth = true;
    this.middlewares.push(validator);
    return this;
  }

  withRoleCheck(allowedRoles: string[]): this {
    if (!this.hasAuth) {
      throw new Error('withRoleCheck() çağrılmadan önce withAuth() çağrılmalı');
    }
    this.middlewares.push((req, res, next) => {
      const userRole = (req as any).user?.role;
      if (!allowedRoles.includes(userRole)) {
        return res.status(403).json({ error: 'Forbidden' });
      }
      next();
    });
    return this;
  }

  route(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, handler: RequestHandler): this {
    const allMiddleware = [...this.middlewares, handler];
    this.router[method.toLowerCase() as 'get'](path, ...allMiddleware);
    return this;
  }

  withErrorHandler(handler?: ErrorRequestHandler): this {
    this.errorHandlers.push(handler || ((err, req, res, next) => {
      console.error('Error:', err);
      res.status(500).json({ error: 'Internal server error' });
    }));
    return this;
  }

  build(): Router {
    // Express'te error handler'lar en sona eklenmeli
    this.errorHandlers.forEach(handler => {
      this.router.use(handler as any);
    });
    return this.router;
  }
}

// Kullanım
const apiRouter = new RouterBuilder()
  .withRequestId()
  .withLogging()
  .withRateLimiting({ requestsPerMinute: 100 })
  .withAuth(jwtAuthMiddleware)
  .withRoleCheck(['admin', 'editor'])
  .route('POST', '/users', createUserHandler)
  .route('GET', '/users/:id', getUserHandler)
  .withErrorHandler()
  .build();

app.use('/api', apiRouter);

Bu pattern middleware sırasını açık hale getirir ve bağımlılık ihlallerini (auth olmadan role check gibi) build time’da yakalar.

Test Data Builder’lar: En Yüksek ROI Uygulaması

Test data builder’lar Builder pattern için en iyi yatırım getirisini sağlar. Testler çeşitli veri senaryolarına ihtiyaç duyar, ama her test için nesneleri manuel oluşturmak can sıkıcı ve kırılgandır.

Mantıklı varsayılanlara sahip test data builder:

import { faker } from '@faker-js/faker';

interface User {
  id: string;
  email: string;
  name: string;
  role: 'admin' | 'user' | 'guest';
  isVerified: boolean;
  createdAt: Date;
  permissions: string[];
}

class UserBuilder {
  private user: User = {
    id: faker.string.uuid(),
    email: faker.internet.email(),
    name: faker.person.fullName(),
    role: 'user',
    isVerified: false,
    createdAt: new Date(),
    permissions: []
  };

  withId(id: string): this {
    this.user.id = id;
    return this;
  }

  withEmail(email: string): this {
    this.user.email = email;
    return this;
  }

  withRole(role: User['role']): this {
    this.user.role = role;
    return this;
  }

  asAdmin(): this {
    this.user.role = 'admin';
    this.user.permissions = ['read', 'write', 'delete', 'manage'];
    return this;
  }

  asVerified(): this {
    this.user.isVerified = true;
    return this;
  }

  withPermissions(...perms: string[]): this {
    this.user.permissions = perms;
    return this;
  }

  build(): User {
    return { ...this.user };
  }

  // Birden fazla user oluşturmak için yardımcı
  static buildList(count: number, customize?: (builder: UserBuilder, index: number) => UserBuilder): User[] {
    return Array.from({ length: count }, (_, i) => {
      const builder = new UserBuilder();
      return customize ? customize(builder, i).build() : builder.build();
    });
  }
}

// Testlerde kullanım
describe('User API', () => {
  it('pagination ile kullanıcıları listeler', async () => {
    const users = UserBuilder.buildList(15, (builder, i) =>
      builder.withEmail(`user${i}@example.com`)
    );
    await db.users.insertMany(users);

    const response = await request(app)
      .get('/api/users?page=1&limit=10')
      .expect(200);

    expect(response.body.data).toHaveLength(10);
    expect(response.body.total).toBe(15);
  });

  it('sadece admin kullanıcıları silmeye izin verir', async () => {
    const admin = new UserBuilder().asAdmin().build();
    const regularUser = new UserBuilder().build();
    const targetUser = new UserBuilder().build();

    await db.users.insertMany([admin, regularUser, targetUser]);

    // Admin silebilir
    await request(app)
      .delete(`/api/users/${targetUser.id}`)
      .set('Authorization', `Bearer ${generateToken(admin)}`)
      .expect(200);

    // Normal kullanıcı silemez
    await request(app)
      .delete(`/api/users/${targetUser.id}`)
      .set('Authorization', `Bearer ${generateToken(regularUser)}`)
      .expect(403);
  });

  it('hassas işlemler için email doğrulaması gerektirir', async () => {
    const unverifiedUser = new UserBuilder().build();
    const verifiedUser = new UserBuilder().asVerified().build();

    await db.users.insertMany([unverifiedUser, verifiedUser]);

    // Doğrulanmamış kullanıcı engellenir
    await request(app)
      .post('/api/sensitive-action')
      .set('Authorization', `Bearer ${generateToken(unverifiedUser)}`)
      .expect(403);

    // Doğrulanmış kullanıcı izin verilir
    await request(app)
      .post('/api/sensitive-action')
      .set('Authorization', `Bearer ${generateToken(verifiedUser)}`)
      .expect(200);
  });
});

Bu yaklaşım test setup kodunu yaklaşık %60 azaltır ve daha önemlisi, User modeline yeni bir zorunlu alan eklendiğinde, düzinelerce test dosyası yerine sadece builder’ın varsayılanlarını güncellemek yeterli olur.

İleri Düzey TypeScript Teknikleri

Daha da güçlü builder’lar için TypeScript’in gelişmiş özelliklerinden nasıl yararlanabileceğimizi keşfedelim.

Conditional Type’larla Progressive Tip Refinement

Belirli metodları ancak diğerleri çağrıldıktan sonra açığa çıkaran builder’lar oluşturabilirsin:

type ConfigState = {
  hasDatabase: boolean;
  hasCache: boolean;
  hasAuth: boolean;
};

class AppConfigBuilder<TState extends Partial<ConfigState> = {}> {
  private config: any = {};

  withDatabase(url: string): AppConfigBuilder<TState & { hasDatabase: true }> {
    this.config.database = url;
    return this as any;
  }

  // Cache config sadece database konfigüre edildikten sonra kullanılabilir
  withCache<T extends TState>(
    this: T extends { hasDatabase: true } ? AppConfigBuilder<T> : never,
    options: CacheOptions
  ): AppConfigBuilder<TState & { hasCache: true }> {
    this.config.cache = options;
    return this as any;
  }

  // Auth için database gerekli
  withAuth<T extends TState>(
    this: T extends { hasDatabase: true } ? AppConfigBuilder<T> : never,
    config: AuthConfig
  ): AppConfigBuilder<TState & { hasAuth: true }> {
    this.config.auth = config;
    return this as any;
  }

  build(): AppConfig {
    return this.config;
  }
}

// Kullanım
const config = new AppConfigBuilder()
  .withDatabase('postgres://localhost/db')
  .withCache({ ttl: 3600 })  // Good: Database konfigüre edildi
  .withAuth({ provider: 'jwt' })  // Good: Database konfigüre edildi
  .build();

// Bad: Bu derlenmez - database olmadan cache kullanamazsın
// const invalid = new AppConfigBuilder().withCache({ ttl: 3600 }).build();

Bu teknik tiplerde kodlanmış bir state machine oluşturur ve konfigürasyon adımlarının doğru sırada gerçekleşmesini sağlar.

Generic Accumulation ile Immutable Builder’lar

Fonksiyonel programlama bağlamları için, state’i değiştirmeyen builder’lar istiyorsun:

class ImmutableQueryBuilder<
  TTable extends keyof Database,
  TSelected extends keyof Database[TTable] = keyof Database[TTable]
> {
  constructor(
    private readonly table: TTable,
    private readonly config: {
      select?: TSelected[];
      where?: Partial<Database[TTable]>;
      limit?: number;
    } = {}
  ) {}

  select<K extends keyof Database[TTable]>(
    ...columns: K[]
  ): ImmutableQueryBuilder<TTable, K> {
    return new ImmutableQueryBuilder(this.table, {
      ...this.config,
      select: columns as any
    });
  }

  where(conditions: Partial<Database[TTable]>): ImmutableQueryBuilder<TTable, TSelected> {
    return new ImmutableQueryBuilder(this.table, {
      ...this.config,
      where: { ...this.config.where, ...conditions }
    });
  }

  limit(count: number): ImmutableQueryBuilder<TTable, TSelected> {
    return new ImmutableQueryBuilder(this.table, {
      ...this.config,
      limit: count
    });
  }

  toSQL(): string {
    const columns = this.config.select?.join(', ') || '*';
    const conditions = this.config.where
      ? ' WHERE ' + Object.entries(this.config.where)
          .map(([k, v]) => `${k} = ${JSON.stringify(v)}`)
          .join(' AND ')
      : '';
    const limitClause = this.config.limit ? ` LIMIT ${this.config.limit}` : '';

    return `SELECT ${columns} FROM ${this.table}${conditions}${limitClause}`;
  }
}

// Her method çağrısı yeni bir instance döndürür
const baseQuery = new ImmutableQueryBuilder('users');
const adminQuery = baseQuery.where({ role: 'admin' });
const userQuery = baseQuery.where({ role: 'user' });

// baseQuery değişmedi - gerçek immutability
console.log(baseQuery.toSQL());  // SELECT * FROM users
console.log(adminQuery.toSQL()); // SELECT * FROM users WHERE role = "admin"
console.log(userQuery.toSQL());  // SELECT * FROM users WHERE role = "user"

Bu pattern, orijinali etkilemeden temel bir konfigürasyonun varyasyonlarını oluşturman gerektiğinde değerlidir.

Builder’ları Ne Zaman Kullanmalı (Ne Zaman Kullanmamalı)

Builder pattern her zaman doğru seçim değil. Pratik bir karar çerçevesi:

Basit Alternatifleri Ne Zaman Kullanmalı:

1. Nesne Basitse (2-3 özellik)

// Bad: Gereksiz karmaşıklık
new UserBuilder()
  .withName('John')
  .withEmail('[email protected]')
  .build();

// Good: Daha iyi
const user = { name: 'John', email: '[email protected]' };

2. TypeScript’in Opsiyonel Parametreleri Yeterli

// Good: İyi - karmaşık kısıtlama yok
function createLogger(options?: {
  level?: 'debug' | 'info' | 'warn' | 'error';
  format?: 'json' | 'text';
}) {
  return new Logger(options);
}

Builder’ları Ne Zaman Kullanmalı:

1. Çok Sayıda Opsiyonel Parametre (5+)

// Çok sayıda seçeneğe sahip config nesneleri fluent API'lerden faydalanır
const server = new ServerBuilder()
  .withPort(3000)
  .withHost('localhost')
  .withCors({ origins: ['https://example.com'] })
  .withRateLimit({ requestsPerMinute: 100 })
  .withCompression()
  .withLogging({ level: 'info' })
  .build();

2. Karmaşık Validasyon veya Kısıtlamalar

// Builder, S3 bucket'in region ve encryption config gerektirdiğini zorlar
const bucket = new S3BucketBuilder()
  .withName('my-bucket')
  .inRegion('us-east-1')
  .withEncryption({ type: 'AES256' })  // Region ayarlandığında zorunlu
  .build();

3. Adım Adım Oluşturma Netliği Artırıyor

// Pipeline oluşturma açık adımlardan faydalanır
const pipeline = new DataPipelineBuilder()
  .readFrom(source)
  .transform(cleanData)
  .filter(isValid)
  .aggregate(byCategory)
  .writeTo(destination)
  .build();

4. Fluent, Keşfedilebilir API’ler Oluşturma

// IDE'ler her adımda mevcut seçenekleri gösterebilir
const query = db.from('users')
  .select('id', 'name')  // IDE mevcut sütunları gösterir
  .where({ status: 'active' })  // IDE geçerli alanları gösterir
  .orderBy('createdAt', 'desc')
  .limit(10);

Yaygın Tuzaklar ve Öğrenilen Dersler

Yaygın hatalar ve bunlardan nasıl kaçınılır:

Tuzak 1: Aşırı Karmaşık Tipler

Sorun: Derlemeyi yavaşlatan ve şifreli hatalar üreten aşırı karmaşık generic tipler.

// Bad: Çok karmaşık - derleme süreleri zarar görüyor, hatalar okunamıyor
class Builder<
  T,
  S extends keyof T,
  R extends Required<Pick<T, S>>,
  O extends Omit<T, S>
> { /* ... */ }

Çözüm: Tip güvenliği ile pragmatizm arasında denge kur. Basit başla ve sadece gerektiğinde karmaşıklık ekle.

// Good: Daha basit, hala yararlı
class Builder<T> {
  private data: Partial<T> = {};

  set<K extends keyof T>(key: K, value: T[K]): this {
    this.data[key] = value;
    return this;
  }

  build(): T {
    // Zorunlu alanlar için runtime validasyon
    return this.data as T;
  }
}

Tuzak 2: Takip Olmadan Mutable State

Sorun: Geleneksel mutable builder’lar eksik konfigürasyonla build() çağrılmasına izin verir.

// Bad: Geçersiz nesne oluşturabilir
class RequestBuilder {
  private url?: string;
  private method?: string;

  build(): Request {
    return { url: this.url!, method: this.method! };  // Undefined olabilir!
  }
}

Çözüm: Generic tip takibi kullan ya da build() içinde validate et.

// Good: Runtime validasyon
build(): Request {
  if (!this.url || !this.method) {
    throw new Error('URL ve method zorunludur');
  }
  return { url: this.url, method: this.method };
}

Tuzak 3: Hot Path’lerde Performans Etkisi

Sorun: Performans kritik döngülerde builder oluşturma.

// Bad: Her veri elemanı için builder oluşturuyor
const results = largeDataset.map(item =>
  new ObjectBuilder()
    .withId(item.id)
    .withValue(item.value)
    .build()
);

Çözüm: Veri dönüşümü için değil, konfigürasyon için builder’ları kullan.

// Good: Veri işleme için düz nesne oluşturma
const results = largeDataset.map(item => ({
  id: item.id,
  value: item.value
}));

// Setup/konfigürasyon için builder kullan
const processor = new DataProcessorBuilder()
  .withBatchSize(1000)
  .withConcurrency(4)
  .withErrorHandler(logError)
  .build();

const results = processor.process(largeDataset);

Tuzak 4: Tutarsız Method İsimlendirme

Sorun: İsimlendirme konvansiyonlarını karıştırmak keşfedilebilirliği azaltır.

// Bad: Tutarsız
new ConfigBuilder()
  .setUrl('...')  // set*
  .withTimeout(30)  // with*
  .addHeader('...')  // add*
  .enableCache()  // enable*

Çözüm: İsimlendirme konvansiyonları belirle ve takip et.

// Good: Tutarlı
new ConfigBuilder()
  .withUrl('...')  // with* tek değerler için
  .withTimeout(30)
  .addHeader('name', 'val') // add* koleksiyonlar için
  .enableCache()  // enable*/disable* boolean'lar için

Tuzak 5: Sadece Build Time’da Validasyon

Sorun: Geçersiz konfigürasyon build() çağrılana kadar yakalanmıyor, potansiyel olarak hatanın kaynağından uzakta.

// Bad: Geç validasyon
class Builder {
  private timeout?: number;

  withTimeout(seconds: number): this {
    this.timeout = seconds;  // Validasyon yok
    return this;
  }

  build() {
    if (this.timeout && this.timeout > 900) {
      throw new Error('Timeout çok büyük');  // Hata kaynaktan uzak
    }
  }
}

Çözüm: Setter metodlarında erken validate et.

// Good: Erken validasyon
withTimeout(seconds: number): this {
  if (seconds <= 0) {
    throw new Error('Timeout pozitif olmalı');
  }
  if (seconds > 900) {
    throw new Error('Timeout 900 saniyeyi geçemez');
  }
  this.timeout = seconds;
  return this;
}

Sonuç: Builder Pattern’in Tatlı Noktası

TypeScript’teki Builder pattern belirli bir problem setini istisnai bir şekilde iyi çözüyor. Constructor’ları güzelleştirmekle ilgili değil - konfigürasyon hatalarını compile time’da yakalamak için tip sisteminden yararlanmak ve hem güçlü hem de keşfedilmesi kolay API’ler oluşturmakla ilgili.

Pattern şu durumlarda parlıyor:

• Infrastructure-as-code oluşturuyorsan (AWS CDK, Terraform CDK)
• Tip güvenli query builder’lara veya API client’larına ihtiyaç duyuyorsan
• Mantıklı varsayılanlarla test verisi üretiyorsan
• Karmaşık middleware veya plugin sistemleri dikkatli sıralama gerektiriyorsa
• Konfigürasyon nesnelerinin birbirine bağımlı kısıtlamaları varsa

Şu durumlarda gereksiz:

• Nesneler basitse (2-3 özellik)
• TypeScript’in opsiyonel parametreleri işi hallediyor
• Performans kritik path’lerde veri işliyorsan

En büyük değer üç alandan geliyor:

1. Infrastructure konfigürasyonu: AWS CDK builder’lar yanlış konfigürasyondan kaynaklanan deployment hatalarını önlüyor
2. Database query builder’lar: Tip güvenli SQL yazım hatalarından kaynaklanan runtime hatalarını önlüyor
3. Test verisi üretimi: Test boilerplate’ini azaltıyor ve testleri daha sürdürülebilir yapıyor

Ana fikir, TypeScript’in tip sisteminin iş kurallarını ve kısıtlamaları doğrudan API’ye kodlamanı sağlamasıdır. Gerekli adımlar tamamlanana kadar derlenmeyen bir builder gördüğünde, sadece daha uygun kod yazmıyorsun - belirli bug sınıflarını imkansız kılıyorsun.

En karmaşık konfigürasyon nesnelerin için basit builder’larla başla ve hangi kısıtlamaların kodlamaya değer olduğunu keşfettikçe kademeli olarak tip güvenliği ekle. Her builder’ın gelişmiş generic tiplere ihtiyacı yok, ama ihtiyaç duyduğunda TypeScript sana gerçekten sağlam API’ler oluşturman için araçlar veriyor.

Kaynaklar

• TypeScript El Kitabı: Generic’ler - Tip güvenli builder uygulamalarının temelini oluşturan generic tipler hakkında resmi TypeScript belgesi.
• TypeScript El Kitabı: Koşullu Tipler - Gelişmiş builder kalıplarında aşamalı tip iyileştirmesi için kullanılan koşullu tipler hakkında resmi belge.
• TypeScript El Kitabı: Eşlenmiş Tipler - Builder API’lerinde konfigürasyon arayüzlerini dönüştürmek için kullanılan eşlenmiş tipler hakkında resmi referans.
• Builder Kalıbı: Refactoring.Guru - Amaç, yapı ve uygulanabilirliği diyagramlarla ele alan Builder yaratıcı kalıbının net açıklaması.
• Tasarım Kalıpları: Yeniden Kullanılabilir Nesne Yönelimli Yazılımın Öğeleri (Gamma ve diğerleri, 1994) - Builder kalıbını ve diğer 22 temel kalıbı tanımlayan orijinal Dörtlü Çete kitabı.
• TypeScript El Kitabı: Tiplerden Tip Oluşturma - Builder generic birikimine uygulanan tip dönüşüm tekniklerine (keyof, typeof, infer) genel bakış sunan resmi TypeScript belgesi.