Typing Singleton Pattern Implementations in TypeScript

Typing Singleton Pattern Implementations in TypeScript

Introduction

Singletons are one of the oldest creational patterns in software design: they ensure a class has exactly one instance and provide a global point of access to that instance. In JavaScript and TypeScript, singletons often appear as simple modules or as classes with static properties. However, getting the typing right in TypeScript—especially for lazy initialization, inheritance, async setup, testability, and registry patterns—takes more care than naive examples.

In this in-depth tutorial you will learn how to design and type multiple singleton variations in TypeScript. We'll cover eager and lazy singletons, module-based singletons, typed registries, per-context singletons using symbols, async initialization strategies, testing-friendly factories, and patterns that keep code maintainable and type-safe. Each pattern includes practical, copy-pasteable code snippets and step-by-step guidance on how to integrate the pattern into real-world projects.

You will also learn how to combine TypeScript features—private/protected constructors, static members, abstract classes, accessor types, and generics—to model singletons safely. Along the way we link to deeper typing topics (class constructors, static members, getters/setters, and more) you can consult for additional detail.

By the end of this guide you'll be able to pick the right singleton pattern for your use case and type it in a way that makes your code easier to test and refactor. We'll also cover common pitfalls, debugging tips, and best practices for production systems.

Background & Context

TypeScript's type system makes it possible to express many singleton behaviors precisely. Unlike plain JavaScript, TypeScript can enforce a class's constructor visibility (private/protected), type the static instance, and provide typed factories or registries. Understanding how to type constructors and static members correctly is central to implementing safe singletons; for a deep dive on constructor typing patterns you can read our guide on typing class constructors.

Singletons are often considered an anti-pattern when abused—especially as implicit globals—because they can make testing and reasoning about dependencies harder. In this article we show how to keep singletons testable via interfaces and factories, and how to scope singletons (e.g., per request or per realm) using symbol-based registries or context-based WeakMaps. When you need to expose controlled accessors, refer to our article on typing getters and setters to ensure types are preserved.

Key Takeaways

• How to implement and type eager vs lazy singletons in TypeScript
• How to model private and protected constructors for singletons
• How to type singletons used for inheritance and abstract factories
• Patterns for async initialization and typed registries
• Strategies to keep singletons testable with dependency injection
• Avoiding common pitfalls like implicit globals and brittle initialization

Prerequisites & Setup

This guide assumes you are familiar with TypeScript basics (classes, interfaces, generics) and have Node.js + TypeScript set up locally. Recommended TypeScript compiler options: "strict": true, "noImplicitAny": true, and "target": "ES2019" or newer. If you need help with private/protected members in classes, consider reviewing our article on typing private and protected class members for nuance and migration tips.

You can run the code examples in a TypeScript project or a sandbox (like TypeScript Playground). Use ts-node or a quick tsc compile step if you want to run examples locally.

Main Tutorial Sections

1) Simple Class-Based Singleton (Eager Initialization)

Eager initialization creates the singleton instance at module load time. It's simple and works well for stateless or cheap-to-create objects.

class Logger {
  private static readonly instance = new Logger();

  private constructor() {
    // private prevents external instantiation
  }

  static getInstance(): Logger {
    return Logger.instance;
  }

  log(msg: string) {
    console.log(msg);
  }
}

const logger = Logger.getInstance();
logger.log('Hello');

Typing notes: the static instance is typed by the class type itself. This pattern leverages static members—if you'd like a thorough reference for static member typing, see typing static class members.

Pros: simple and thread-safe in JS (single-threaded), easy typing. Cons: instance created even if unused and harder to customize in tests unless you provide injection points.

2) Lazy Initialization with getInstance()

Lazy singletons delay creation until the first call to getInstance. This is useful for expensive initialization.

class ConfigService {
  private static instance?: ConfigService;

  private constructor(private config: Record<string, unknown>) {}

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

  get(key: string) { return (this.config as any)[key]; }
}

Typing the instance as ConfigService | undefined forces checks or initialization before use. For flexibility, you can add init() overloads that accept configuration. Lazy singletons are great when the initialization depends on runtime values.

3) Module-Based Singleton (export default new ...)

Bundlers and Node module semantics make module-level singletons trivial: export a constructed instance from a module.

// telemetry.ts
export default new TelemetryClient();

// usage
import telemetry from './telemetry';
telemetry.track('event');

This is easy and often the most idiomatic approach in TypeScript projects. Downsides: replacing the singleton in tests is harder unless your module loader supports mocking or you provide setter APIs. To keep testability, export a factory function as well or an interface to allow substitution.

4) Singletons with Inheritance and Protected Constructors

If you want subclassing or abstract base behavior, a protected constructor is ideal. This allows a single instance per concrete subclass while preventing direct external instantiation. For nuances on abstract members, see typing abstract class members.

abstract class BaseService {
  protected constructor(public name: string) {}
}

class ConcreteService extends BaseService {
  private static _instance?: ConcreteService;
  private constructor() { super('concrete'); }

  static getInstance(): ConcreteService {
    if (!this._instance) this._instance = new ConcreteService();
    return this._instance;
  }
}

Use protected constructors when you want a class hierarchy but still enforce controlled instantiation. Typing the base class helps with polymorphism and dependency inversion.

5) Generic Singleton Registry (Typed by Constructor)

Sometimes you need one instance per class type (a registry). A typed registry can map constructors to instances using generics for compile-time safety.

type Constructor<T> = new (...args: any[]) => T;

class SingletonRegistry {
  private static instances = new Map<Constructor<any>, any>();

  static get<T>(ctor: Constructor<T>, factory?: () => T): T {
    if (!this.instances.has(ctor)) {
      if (!factory) throw new Error('No instance and no factory provided');
      this.instances.set(ctor, factory());
    }
    return this.instances.get(ctor);
  }
}

// usage
class A { a = 1; }
const a = SingletonRegistry.get(A, () => new A());

Here the types ensure get(A) returns A. The registry approach is excellent when you have multiple singletons and want a consistent API for retrieval and testing.

6) Async Initialization and Typed Promises

When a singleton needs async setup (e.g., DB connection), provide an async init and type the public API to indicate readiness.

class DB {
  private static instance?: DB;
  private connected = false;

  private constructor() {}

  static async getInstance(): Promise<DB> {
    if (!DB.instance) {
      DB.instance = new DB();
      await DB.instance.init();
    }
    return DB.instance;
  }

  private async init() {
    // simulate async setup
    await new Promise(r => setTimeout(r, 100));
    this.connected = true;
  }

  query(sql: string) {
    if (!this.connected) throw new Error('DB not initialized');
    return [] as any[];
  }
}

Be explicit in types: getInstance() returns Promise<DB>. Consumers must await it. Consider adding a synchronous getIfReady() that returns DB | undefined for code that conditionally uses the instance.

7) Per-Context Singletons with Symbols and Global Registries

Modules produce global singletons per realm. If you need a truly global registry (e.g., across multiple bundles or third-party code), use a symbol on the global object to store the singleton. Typing symbol keys is covered in our guide on typing symbols as object keys.

const GLOBAL_KEY = Symbol.for('my.app.singleton');

declare global {
  interface GlobalThis { [GLOBAL_KEY]?: any }
}

if (!(globalThis as any)[GLOBAL_KEY]) {
  (globalThis as any)[GLOBAL_KEY] = { /* instance */ };
}

const instance = (globalThis as any)[GLOBAL_KEY];

To keep types safe, wrap global access in a typed API and, if you must extend the global type, do so via declaration merging. Our piece on extending the window object shows patterns you can apply to globalThis safely.

8) Testability: Exposing Factories and Interfaces

Hard-coded singletons are difficult to test. Instead of calling Class.getInstance() everywhere, depend on interfaces or factories so tests can inject mocks.

interface ILogger { log(msg: string): void }

class Logger implements ILogger {
  private static instance?: Logger;
  private constructor() {}
  static getInstance() { return this.instance ??= new Logger(); }
  log(msg: string) { console.log(msg); }
}

// prefer injecting ILogger in constructors:
class Greeter {
  constructor(private logger: ILogger) {}
  greet() { this.logger.log('hi'); }
}

// test
const mock: ILogger = { log: () => {/* noop */} };
new Greeter(mock).greet();

When writing code that uses singletons, design your modules to accept dependencies as parameters (constructor injection or function parameters) rather than importing singletons directly. This improves testability and reduces coupling.

For debugging issues introduced by singletons (initialization order, multiple copies across bundles), our guide on debugging TypeScript code has practical tips for mapping runtime failures back to TypeScript sources.

9) Private Fields and Accessors in Singletons

Prefer private fields and typed accessors when exposing singleton state. Read more about accessors in typing getters and setters.

class Settings {
  private static _instance?: Settings;
  private _cache = new Map<string, string>();

  private constructor() {}

  static getInstance() { return this._instance ??= new Settings(); }

  get(key: string): string | undefined { return this._cache.get(key); }
  set(key: string, value: string) { this._cache.set(key, value); }

  get size(): number { return this._cache.size; }
}

With private and explicit accessor return types, consumers get clear compile-time guarantees. Use accessor types for derived values or to enforce invariants on set operations.

Advanced Techniques

Beyond single-instance patterns, you can combine TypeScript features and runtime techniques for sophisticated behaviors: implement a typed service locator using generics and conditional types, create per-request singletons scoped by a context object (using WeakMap<Context, Instance>), or provide a typed plugin system backed by a singleton registry. For example, WeakMap allows garbage-collectable per-context instances:

const contexts = new WeakMap<object, Map<Function, any>>();
function getForContext<T>(ctx: object, ctor: Constructor<T>, factory: () => T): T {
  let map = contexts.get(ctx);
  if (!map) { map = new Map(); contexts.set(ctx, map); }
  if (!map.has(ctor)) map.set(ctor, factory());
  return map.get(ctor);
}

Other advanced ideas include: creating a typed plugin lifecycle with initialization phases (init, start, stop) and using discriminated unions for different singleton states (uninitialized, initializing, ready, failed). Use TypeScript's mapped types and conditional types to generate strongly-typed registries that help consumers discover available services at compile time.

Performance tip: singletons avoid repeated allocation but can become bottlenecks if used with blocking synchronous initialization; prefer lazy and async patterns when setup is expensive. Also avoid holding huge in-memory caches on singletons unless eviction and memory bounds are enforced.

Best Practices & Common Pitfalls

Dos:

• Prefer module singletons or simple lazy singletons for straightforward use cases.
• Use interfaces and dependency injection to keep code testable.
• Use protected/private constructors to enforce controlled instantiation.
• Type static properties and factories precisely to avoid unsafe casts.

Don'ts:

• Don’t use singletons as implicit global state for everything—this increases coupling and reduces testability.
• Avoid hiding async setup behind synchronous getters; prefer explicit Promise-based init paths.
• Don’t store heavy resources in singletons without lifecycle management (close/dispose).

Common pitfalls:

• Duplicate singletons across bundles: bundlers or multiple copies of a library can produce different instances. Use a global symbol-based registry to coordinate across realms when needed, as described earlier.
• Initialization order bugs: if singletons depend on each other during module load, you can end up with undefined or partially initialized instances. Use lazy getters or deferring initialization into explicit init functions to avoid this.

Troubleshooting tips: add diagnostic guards in getInstance() to detect re-entrancy or partially-initialized states and log helpful messages that can be traced via source maps. Refer to our debugging guide for advanced strategies: debugging TypeScript code.

Real-World Applications

Singletons are useful for shared services such as logging, telemetry, configuration caches, database connection pools, and platform adapters. In large applications, prefer a hybrid approach: use a singleton-backed service locator for truly global services, but pass services by dependency injection for domain logic. When building Node.js apps that use built-in modules (like streams, fs, or http), consult structured typing patterns—they often shape how you design your singleton surfaces. You might find our article on typing Node.js built-in modules helpful when integrating typed singletons with Node APIs.

For front-end apps, consider scoping singletons per app instance (e.g., when embedding apps in a host page). Use symbol-based keys or extend the window object safely; see typing global variables: extending the window object for patterns.

Conclusion & Next Steps

Singletons are a pragmatic tool when used intentionally. With TypeScript you can express singleton invariants clearly and prevent many runtime errors via types. Start by choosing a convention in your codebase (module-level vs class-based), prefer dependency injection where possible, and add typed factories for testability. Next, explore constructor typing and static member patterns in more detail via our guides on typing class constructors and typing static class members.

Enhanced FAQ

Q: Should I always use singletons for shared services? A: No. Singletons are appropriate when you truly need one shared instance (e.g., a database pool or global logger). For domain logic, prefer dependency injection. This makes components easier to test and more composable.

Q: How do I test code that uses a singleton? A: Avoid importing singletons directly everywhere. Depend on interfaces or accept the singleton via constructor parameters. For modules that must read singletons, provide test-level setters or factory injection. The registry approach also allows tests to inject test instances into the registry.

Q: Are singletons safe in server environments with multiple requests? A: Singletons exist per process (or per VM realm). For multi-tenant or per-request data, singletons can cause data leaks between requests. Use scoped registries (WeakMap keyed by request context) or avoid storing mutable per-request state in singletons.

Q: How do I handle async initialization and ensure code waits for readiness? A: Provide explicit async init() or make getInstance() return Promise<Instance>. You can also provide a getIfReady() that returns Instance | undefined for non-blocking code paths. Avoid hiding asynchronous behavior behind synchronous APIs.

Q: How can I avoid duplicate singletons across bundles or versions? A: Use a symbol on globalThis (Symbol.for) as a registry key, or design your library to accept an externally provided instance. Coordinating across bundle boundaries is often necessary for runtime plugins or many-library scenarios. See the section on symbols and global registries and our piece on typing symbols as object keys for details.

Q: Should I use private or protected constructors for singletons? A: Use private to prevent subclassing and direct instantiation. Use protected when you want subclassing but still want to control instantiation through static APIs. For more on private/protected semantics in TypeScript, review typing private and protected class members.

Q: How do singletons interact with subclassing and abstract classes? A: When combining singletons with subclassing, consider using a protected constructor in the base class and a static getInstance() per concrete subclass. If the base class is abstract and intended to provide shared behavior, type it carefully to ensure that derived classes' getInstance() returns concrete types; see typing abstract class members for patterns.

Q: Any performance concerns with singletons? A: Singletons can improve performance by avoiding repeated allocation, but they can also become contention points (logical contention, not CPU threads in JS). Avoid synchronous heavy initialization in module load time and consider lazy or async initialization. Also add eviction and bounded caches if a singleton holds large amounts of memory.

Q: Is a module-exported instance better than a class-based singleton? A: Both are valid. Module-exported instances are idiomatic and concise. Class-based singletons give more control (lazy init, protected constructors). Choose based on your need for testability and initialization control.

Q: Where can I learn more about the TypeScript features used for typing singletons? A: A few relevant guides from our series:

• Constructor and factory typing: typing class constructors
• Static members and patterns: typing static class members
• Private/protected nuance: typing private and protected class members
• Symbols and global keys: typing symbols as object keys
• Getters/setters: typing getters and setters in classes and objects

If you run into runtime issues debugging initialization order or trace mapping, consult debugging TypeScript code for practical tools and strategies.

Further reading: If your singleton interacts with iterators, async iterators, or typed DOM APIs for browser-based singletons, consider the related guides on typed iterators and DOM typing to keep your API consistent and safe: typing iterators and iterables and typing async iterators and async iterables. For Node.js specific integrations, see typing Node.js built-in modules for patterns around streams and resources.

This guide should equip you with the patterns and typings needed to select and implement appropriate singleton patterns for intermediate TypeScript projects. Practice by converting a small shared service in your codebase to a typed singleton using the approaches above, and add tests that verify initialization and substitution via interfaces.