JS Patterns Course

Yaradıcı (Creational)

Singleton

Bir class-dan proqram boyu yalnız bir instance yaratmaq və onu hər yerdə paylaşmaq.

Başlanğıc · 14 dəqiqə · creational, instance, global state, module

Problem

Tutaq ki, layihədə sayğac var. Qırmızı düymə də, mavi düymə də onu artırmalıdır və hər ikisi eyni rəqəmi göstərməlidir.

İlk yanaşma — adi class yazıb hər faylda new çağırmaq:

// ❌ Pis: hər fayl özünə ayrı sayğac yaradır
class Counter {
  constructor() {
    this.count = 0;
  }

  increment() {
    this.count += 1;
    return this.count;
  }
}

// red-button.js
const redCounter = new Counter();

// blue-button.js
const blueCounter = new Counter();

redCounter.increment();
console.log(blueCounter.count); // 0 — qirmizi duymenin klikini gormedi

Nə partlayır:

  • Hər new Counter() yeni yaddaş sahəsi və yeni count yaradır.
  • İki fayl eyni obyektdən danışdığını düşünür, əslində iki ayrı obyekt var.
  • Səhv tez tapılmır: kod xəta vermir, sadəcə rəqəmlər uyğun gəlmir.

Bizə lazım olan şey — proqramın hər yerindən görünən tək obyekt.

Pattern nədir

Singleton — class-ın yalnız bir instance-ının yaradılmasına icazə verən və o instance-a qlobal giriş nöqtəsi təqdim edən yaradıcı (creational) pattern-dir.

Analogiya: binanın elektrik sayğacı. Mənzildə neçə adam yaşamasından asılı olmayaraq sayğac birdir. Kimsə işığı yandıranda hamının gördüyü rəqəm dəyişir. Hər otağa ayrıca sayğac qoysan, ümumi sərfiyyatı heç vaxt doğru hesablaya bilməzsən.

Struktur

İştirakçıRolu
Singleton classYalnız bir instance yaradılmasını təmin edir
instance dəyişəniYaradılmış yeganə instance-a istinadı saxlayır
Constructor yoxlamasıİkinci new çağırışını bloklayır və ya mövcud instance-ı qaytarır
Modul export-uInstance-a qlobal giriş nöqtəsi verir
İstifadəçi modullarInstance-ı import edir, özləri yaratmır
  red-button.js --import--+
                          |
                          v
                    counter.js
                 +------------------+
                 |  instance (tek)  |
                 |  count: 3        |
                 +------------------+
                          ^
                          |
  blue-button.js --import-+

  Iki fayl - bir obyekt. increment() cagirisi hamiya gorunur.

Addım-addım implementasiya

1. Sadə class — hələ Singleton deyil

let counter = 0;

class Counter {
  getInstance() {
    return this;
  }

  getCount() {
    return counter;
  }

  increment() {
    counter += 1;
    return counter;
  }

  decrement() {
    counter -= 1;
    return counter;
  }
}

const counter1 = new Counter();
const counter2 = new Counter();

console.log(counter1.getInstance() === counter2.getInstance()); // false

Niyə belə?

  • counter dəyişəni modul səviyyəsindədir, ona görə say paylaşılır.
  • Amma counter1 və counter2 fərqli obyektlərdir — === müqayisəsi false verir.
  • Yəni bu hələ Singleton deyil: new istənilən qədər instance yarada bilir.

Qeyd: orijinal patterns.dev nümunəsində ++counter yazılıb. Burada Airbnb qaydasına görə (no-plusplus) counter += 1 işlədilir — davranış eynidir.

2. İkinci instance-ı bloklamaq

let instance;
let counter = 0;

class Counter {
  constructor() {
    if (instance) {
      throw new Error('You can only create one instance!');
    }

    instance = this;
  }

  getInstance() {
    return this;
  }

  getCount() {
    return counter;
  }

  increment() {
    counter += 1;
    return counter;
  }

  decrement() {
    counter -= 1;
    return counter;
  }
}

const counter1 = new Counter();
const counter2 = new Counter(); // Error: You can only create one instance!

Niyə belə?

  • instance modul səviyyəsində saxlanılır — modul bir dəfə yüklənir, deməli yoxlama bütün import-lar üçün ortaqdır.
  • Constructor ikinci dəfə işə düşəndə instance artıq doludur, xəta atılır.
  • Xəta atmaq sərt variantdır. Yumşaq variant — mövcud instance-ı qaytarmaq: if (instance) return instance;. Hansını seçdiyini komanda ilə razılaşdır: xəta səhvi tez üzə çıxarır, qaytarma isə kodun səssiz işləməsinə imkan verir.

3. Instance-ı dondurub export etmək

// counter.js
let instance;
let counter = 0;

class Counter {
  constructor() {
    if (instance) {
      throw new Error('You can only create one instance!');
    }

    instance = this;
  }

  getCount() {
    return counter;
  }

  increment() {
    counter += 1;
    return counter;
  }

  decrement() {
    counter -= 1;
    return counter;
  }
}

const singletonCounter = Object.freeze(new Counter());

export default singletonCounter;

Niyə belə?

  • Modul bir dəfə icra olunur, ona görə new Counter() bir dəfə işləyir. İstifadəçi kod artıq new yazmır — hazır obyekt alır.
  • Object.freeze obyektə yeni xassə əlavə etməyi və mövcudlarını dəyişməyi bloklayır. Yəni kimsə singletonCounter.getCount = () => 999 yaza bilməz.
  • Diqqət: Object.freeze dayaz (shallow) işləyir. counter dəyişəni obyektin içində deyil, modul scope-undadır — ona görə increment hələ də işləyir. Əgər vəziyyəti obyektin içində saxlasaydın, freeze onu da dondurardı.

4. TypeScript versiyası

// counter.ts
class Counter {
  private static instance: Counter | undefined;

  private count = 0;

  private constructor() {}

  static getInstance(): Counter {
    if (!Counter.instance) {
      Counter.instance = new Counter();
    }

    return Counter.instance;
  }

  getCount(): number {
    return this.count;
  }

  increment(): number {
    this.count += 1;
    return this.count;
  }

  decrement(): number {
    this.count -= 1;
    return this.count;
  }
}

export const counter = Counter.getInstance();

Niyə belə?

  • private constructor — kompilyator new Counter() yazmağa build zamanı icazə vermir. JS variantındakı kimi runtime xətasını gözləmirsən.
  • private static instance instance-ı class-ın öz daxilində saxlayır, modul səviyyəsində sərbəst dəyişən yaratmır.
  • getInstance lazy işləyir: instance ilk çağırışda yaranır, ondan sonra eyni obyekt qaytarılır.

5. JavaScript-də ən sadə variant — adi obyekt

// counter.js
const counter = {
  count: 0,

  increment() {
    this.count += 1;
    return this.count;
  },

  decrement() {
    this.count -= 1;
    return this.count;
  },
};

export default counter;

Niyə belə?

  • Java və C++-da obyekt yaratmaq üçün mütləq class lazımdır — Singleton orada dilin məhdudiyyətini həll edir. JavaScript-də obyekti birbaşa yaratmaq olar.
  • Obyektlər istinadla (by reference) ötürülür: red-button.js və blue-button.js eyni obyekti import edir.
  • Nəticə əvvəlki class variantı ilə eynidir, amma kod üç dəfə qısadır. JavaScript-də class-lı Singleton çox vaxt artıq yükdür.

Real nümunə

Brauzerdə bir dəfə qurulmalı olan resurs — məsələn analitika növbəsi. Bunu Next.js client komponentində istifadə edək:

// src/shared/lib/analytics.ts
interface AnalyticsEvent {
  name: string;
  payload?: Record<string, unknown>;
}

const queue: AnalyticsEvent[] = [];

export const analytics = Object.freeze({
  track(name: string, payload?: Record<string, unknown>): void {
    queue.push({ name, payload });
  },

  flush(): AnalyticsEvent[] {
    const events = [...queue];
    queue.length = 0;
    return events;
  },
});
// src/features/lesson-rating/ui/rating-button.tsx
'use client';

import { analytics } from '@/shared/lib/analytics';

interface RatingButtonProps {
  slug: string;
}

export const RatingButton = ({ slug }: RatingButtonProps) => (
  <button type="button" onClick={() => analytics.track('lesson_rated', { slug })}>
    Faydalı oldu
  </button>
);

Hansı hissə pattern-dir: analytics obyekti bir dəfə yaranır və bütün komponentlər eyni növbəyə yazır. Qalan hissə adi React kodudur.

Next.js-də vacib xəbərdarlıq: modul səviyyəli instance serverdə bütün sorğular arasında paylaşılır. Ona görə Singleton-da istifadəçiyə aid məlumat (sessiya, səbət, cari user) saxlamaq olmaz — bir istifadəçinin datası digərinə görünə bilər. Serverdə Singleton yalnız istifadəçidən asılı olmayan resurslar üçün uyğundur: DB connection pool, konfiqurasiya, logger.

Nə vaxt istifadə et

  • Proqram boyu tək nüsxəsi olmalı resurs var: DB connection pool, logger, konfiqurasiya obyekti, cache client.
  • Resursun yaradılması bahalıdır və təkrar yaratmağın mənası yoxdur.
  • Vəziyyət (state) istifadəçidən asılı deyil və dəyişməzdir, yaxud yalnız nəzarətli şəkildə dəyişir.

Nə vaxt istifadə etmə

  • Class-ın bir neçə instance-ı lazım ola bilər — Singleton bunu dizayn olaraq bağlayır.
  • Serverdə istifadəçiyə aid vəziyyət saxlanılır — əvəzinə sorğu başına yaradılan obyekt (request scope) işlət.
  • React-də qlobal UI state lazımdır — əvəzinə Redux, Zustand və ya React Context. Bunlar da qlobal vəziyyətdir, amma yalnız oxumaq üçün: komponent state-i birbaşa dəyişmir, action göndərir, reducer dəyişir.
  • Modul səviyyəli sadə dəyişən və ya dependency injection eyni nəticəni daha rahat test olunan şəkildə verir.

Tələlər və anti-pattern-lər

1. Dəyişkən qlobal vəziyyət

Singleton qlobal dəyişənin gözəl paltar geymiş versiyasıdır. Kodun bir hissəsi vəziyyəti dəyişir, digəri oxuyur — icra sırası vacib olur. Layihə böyüdükcə "bu dəyəri kim dəyişdi?" sualına cavab tapmaq çətinləşir.

// ❌ Pis: heç kim bilmir bu obyekti kim dəyişir
export const appState = { user: null, theme: 'light', cart: [] };
// ✅ Yaxşı: yalnız oxunan konfiqurasiya, dəyişən vəziyyət ayrıca idarə olunur
export const appConfig = Object.freeze({
  apiUrl: 'https://api.example.com',
  theme: 'light',
});

2. Dependency hiding

superCounter.js faylını import edəndə onun içəridə Singleton-a toxunduğu görünmür. Sən sadəcə funksiya çağırırsan, amma qlobal vəziyyət dəyişir.

// ❌ Pis: asililiq gizlidir
import counter from './counter';

export const superIncrement = () => {
  counter.increment();
  counter.increment();
  counter.increment();
};
// ✅ Yaxşı: asililiq parametr kimi acıq verilir (dependency injection)
export const superIncrement = (target) => {
  target.increment();
  target.increment();
  target.increment();
};

İkinci variantda funksiyaya istənilən sayğac vermək olar — testdə saxta (fake) obyekt ötürürsən, qlobal vəziyyətə toxunmursan.

3. Test sırasından asılılıq

Testlər eyni instance-ı bölüşdüyü üçün bir testin dəyişikliyi digərinə keçir. Nəticə: testlər tək-tək keçir, birlikdə düşür. Həlli aşağıdakı "Test etmək" bölməsindədir.

4. HMR və çoxlu bundle — tək instance əslində iki olur

Development-də hot reload modulu yenidən yükləyəndə yeni instance yaranır. Serverdə bu, məsələn, hər dəyişiklikdə yeni DB connection deməkdir.

// ✅ Yaxşı: dev-de instance globalThis-de saxlanilir
interface Logger {
  log: (message: string) => void;
}

const createLogger = (): Logger => ({
  log: (message: string) => {
    console.warn(`[app] ${message}`);
  },
});

const globalCache = globalThis as typeof globalThis & { appLogger?: Logger };

export const logger = globalCache.appLogger ?? createLogger();

if (process.env.NODE_ENV !== 'production') {
  globalCache.appLogger = logger;
}

globalThis HMR-dən sonra da qalır, ona görə ikinci yükləmədə eyni logger qaytarılır. Production-da bu qeyd yazılmır — orada modul onsuz da bir dəfə icra olunur.

Oxşar pattern-lərlə müqayisə

PatternƏsas fərqNə vaxt onu seç
Module patternClass yoxdur, sadəcə modul export-u; instance nəzarəti də yoxdurJavaScript-də sadə paylaşılan obyekt lazımdırsa
FactoryHər çağırışda yeni obyekt qaytarırEyni tipdən çox sayda obyekt lazımdırsa
Dependency InjectionObyekt yuxarıdan ötürülür, import olunmurTest olunabilənlik prioritetdirsə
Redux / ZustandQlobal, amma yalnız oxunan state; dəyişiklik action iləReact-də qlobal UI state üçün
React ContextAğac üzrə paylaşılır, provider-dən asılıdırVəziyyət komponent ağacına bağlıdırsa

Test etmək

Singleton-un vəziyyəti testlər arasında qalır. Ona görə hər testdən əvvəl ya modulu yenidən yüklə, ya da instance-a reset metodu əlavə et.

// counter.test.js (Vitest)
import { beforeEach, describe, expect, it, vi } from 'vitest';

describe('counter singleton', () => {
  beforeEach(() => {
    vi.resetModules();
  });

  it('eyni instance-i qaytarir', async () => {
    const first = await import('./counter');
    const second = await import('./counter');

    expect(first.default).toBe(second.default);
  });

  it('her testde temiz veziyyetle baslayir', async () => {
    const { default: counter } = await import('./counter');

    counter.increment();

    expect(counter.getCount()).toBe(1);
  });
});

vi.resetModules() modul keşini təmizləyir — növbəti import modulu yenidən icra edir və təzə instance yaradır. Jest-də eyni işi jest.resetModules() görür.

Özünü yoxla

  1. Aşağıdakı kod nə çap edəcək və niyə?
class Counter {
  getInstance() {
    return this;
  }
}

const a = new Counter();
const b = new Counter();

console.log(a.getInstance() === b.getInstance());
Cavab

false. new hər dəfə yeni obyekt yaradır, getInstance isə sadəcə this-i qaytarır. a və b fərqli instance-lardır, ona görə === müqayisəsi false verir. Bu class hələ Singleton deyil.

  1. Object.freeze(new Counter()) yazsan da increment() işləyir. Niyə?
Cavab

Çünki say obyektin içində deyil, modul scope-undakı counter dəyişənindədir. Object.freeze yalnız obyektin öz xassələrini dondurur və dayaz (shallow) işləyir. Vəziyyəti this.count kimi saxlasaydın, freeze onun dəyişməsini bloklayardı.

  1. Serverdə (Next.js) Singleton-da istifadəçinin səbətini saxlamaq niyə təhlükəlidir?
Cavab

Modul instance-ı server prosesində bütün sorğular arasında paylaşılır. Bir istifadəçinin səbəti digərinin sorğusunda görünə bilər. İstifadəçiyə aid data sorğu başına yaradılmalıdır (request scope), Singleton isə yalnız istifadəçidən asılı olmayan resurslar üçündür.

  1. Testlər tək-tək keçir, birlikdə işlədəndə düşür. Singleton baxımından səbəb nədir?
Cavab

Testlər eyni instance-ı bölüşür. Əvvəlki testin dəyişdirdiyi vəziyyət növbəti testə keçir, deməli nəticə testlərin sırasından asılı olur. Həlli: hər testdən əvvəl vi.resetModules() və ya jest.resetModules() çağırmaq, yaxud instance-a açıq reset metodu vermək.

  1. JavaScript-də class-lı Singleton əvəzinə nə vaxt adi obyekt kifayətdir?
Cavab

Demək olar həmişə. JavaScript-də obyekti birbaşa yaratmaq mümkündür, ona görə "yalnız bir instance" məhdudiyyətini class ilə qurmağa ehtiyac yoxdur — modul səviyyəsində yaradılmış obyekt onsuz da təkdir. Class variantı yalnız irsiyyət, private sahələr və ya lazy yaradılma lazım olanda üstünlük qazanır.

Tapşırıq

src/shared/lib/feature-flags.ts faylında feature flag store yaz: flag-ları oxumaq üçün isEnabled(name) metodu, testdən əvvəl vəziyyəti sıfırlamaq üçün reset() metodu olsun. Store bütün proqramda tək olmalıdır. Sonra dependency hiding tələsindən qaçmaq üçün flag-a baxan funksiyanı elə yaz ki, store-u parametr kimi qəbul etsin.

Qəbul meyarları:

  • İki fərqli fayldan import ediləndə eyni obyekt gəlir (=== testi keçir).
  • Export olunan obyekt Object.freeze ilə qorunub.
  • reset() çağırışından sonra bütün flag-lar ilkin vəziyyətə qayıdır.
  • Flag oxuyan funksiya store-u import etmir, parametr kimi alır.
  • Vitest ilə ən azı 2 test yazılıb: paylaşılan instance və reset davranışı.

Xülasə

  • Singleton class-ın yalnız bir instance-ının yaradılmasını təmin edir və ona qlobal giriş verir.
  • JavaScript-də modulun özü onsuz da bir dəfə icra olunur — çox vaxt adi obyekt export etmək kifayətdir, class artıq yükdür.
  • Object.freeze obyekti təsadüfi dəyişikliklərdən qoruyur, amma dayaz işləyir.
  • Əsas zərəri qlobal dəyişkən vəziyyətdir: gizli asılılıq, test sırasından asılılıq, izlənilməsi çətin data axını.
  • Serverdə (Next.js) instance sorğular arasında paylaşılır — orada yalnız istifadəçidən asılı olmayan resurslar saxla; React-də qlobal state üçün Redux, Zustand və ya Context seç.

Mənbələr