DEV Community: Abanoub Kerols

Using Next.js as a Backend for Frontend (BFF)

Abanoub Kerols — Fri, 11 Sep 2026 21:34:10 +0000

When building a modern web application, the frontend often needs to communicate with multiple backend services:

Browser
   │
   ├── Auth Service
   ├── Product Service
   ├── Order Service
   └── Notification Service

This works, but it makes the frontend tightly coupled to the backend architecture.

A better approach in some systems is to introduce a Backend for Frontend (BFF).

Browser
   │
   ▼
Next.js BFF
   │
   ├── Auth Service
   ├── Product Service
   ├── Order Service
   └── Notification Service

What is a BFF?

A BFF is a backend layer specifically designed for a particular frontend.

Instead of exposing all backend services directly to the browser, the frontend communicates with the BFF, and the BFF communicates with the internal services.

This gives us a place to handle:

Authentication
Authorization
Request validation
API aggregation
Response transformation
Caching
Hiding internal service URLs

Next.js as a BFF

Next.js can implement a BFF using Route Handlers.

For example:

app/
└── api/
    └── products/
        └── route.ts

// app/api/products/route.ts

export async function GET() {
  const response = await fetch(
    `${process.env.PRODUCT_SERVICE_URL}/products`
  );

  if (!response.ok) {
    return Response.json(
      { message: "Failed to fetch products" },
      { status: 500 }
    );
  }

  const products = await response.json();

  return Response.json(products);
}

Now the browser calls:

GET /api/products

Instead of directly calling:

GET http://product-service:3002/products

The architecture becomes:

Browser
   │
   │ GET /api/products
   ▼
Next.js BFF
   │
   │ GET /products
   ▼
Product Service

The internal service URL remains server-side.

API Aggregation

One of the most useful BFF features is aggregation.

Imagine a dashboard needs data from four different services:

User Service
Order Service
Notification Service
Recommendation Service

Instead of making four requests from the browser:

Browser
 ├── GET /users/me
 ├── GET /orders
 ├── GET /notifications
 └── GET /recommendations

The BFF can expose a single endpoint:

GET /api/dashboard

And fetch the data in parallel:

// app/api/dashboard/route.ts

export async function GET() {
  const [
    user,
    orders,
    notifications,
    recommendations,
  ] = await Promise.all([
    fetch(`${process.env.USER_SERVICE_URL}/me`)
      .then(res => res.json()),

    fetch(`${process.env.ORDER_SERVICE_URL}/orders`)
      .then(res => res.json()),

    fetch(`${process.env.NOTIFICATION_SERVICE_URL}/notifications`)
      .then(res => res.json()),

    fetch(`${process.env.RECOMMENDATION_SERVICE_URL}/recommendations`)
      .then(res => res.json()),
  ]);

  return Response.json({
    user,
    orders,
    notifications,
    recommendations,
  });
}

Now the browser only needs:

GET /api/dashboard

The BFF handles the complexity behind the scenes.

Response Transformation

The BFF can also transform backend responses into a format that is better suited for the frontend.

For example, a backend might return:

{
  "id": 15,
  "first_name": "Abanoub",
  "last_name": "Kerols",
  "internal_role_id": 7
}

But the frontend may only need:

{
  "id": 15,
  "name": "Abanoub Kerols"
}

The BFF can perform this transformation:

return Response.json({
  id: user.id,
  name: `${user.first_name} ${user.last_name}`,
});

This prevents the frontend from becoming dependent on internal backend models.

Authentication

A BFF can also be useful for authentication.

For example:

Browser
   │
   │ HttpOnly Cookie
   ▼
Next.js BFF
   │
   │ Authorization: Bearer <token>
   ▼
Backend Service

The BFF can read the server-side authentication state and attach the appropriate credentials when calling internal services.

This can help keep sensitive tokens away from client-side JavaScript.

The Important Architectural Boundary

Using Next.js as a BFF does not mean moving all business logic into Next.js.

A good separation is:

             Next.js
        ┌───────────────┐
        │ UI            │
        │ BFF           │
        │ Authentication│
        │ Aggregation   │
        │ Transformation│
        └───────┬───────┘
                │
                ▼
        Backend Services
        ┌───────────────┐
        │ Business Logic│
        │ Domain Rules  │
        │ Data Access   │
        └───────────────┘

The BFF should mainly adapt backend capabilities to the needs of the frontend, while important domain logic remains in the backend services.

Final Architecture

                    Browser
                       │
                       │ HTTPS
                       ▼
              ┌─────────────────┐
              │     Next.js      │
              │       BFF        │
              │                 │
              │ Auth            │
              │ Validation      │
              │ Aggregation     │
              │ Transformation  │
              │ Caching         │
              └────────┬────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       Auth API    Product API   Order API
          │            │            │
          ▼            ▼            ▼
       Database     Database     Database

The key idea

Next.js doesn't have to replace your backend. It can become the backend layer specifically designed for your frontend.

That's the core idea behind using Next.js as a Backend for Frontend (BFF).

Dependency Injection in Angular: From Constructor Injection to Modern DI

Abanoub Kerols — Thu, 10 Sep 2026 18:12:21 +0000

Dependency Injection (DI) is one of the most important concepts in Angular.

If you understand Angular DI deeply, you understand much more than how to inject a service into a component. You understand how Angular creates objects, controls their lifetime, chooses implementations, scopes dependencies, handles configuration, supports testing, and builds hierarchical application architecture.

And Angular DI has evolved significantly.

We started with:

constructor(private userService: UserService) {}

Then Angular introduced:

private userService = inject(UserService);

Modern Angular goes even further with:

EnvironmentInjector
InjectionToken
useValue
useClass
useFactory
useExisting
multi
providedIn
providers
viewProviders
Optional
Self
SkipSelf
Host
forwardRef
runInInjectionContext
functional guards and resolvers
provider functions such as provideRouter() and provideHttpClient()
environment-level providers
hierarchical scopes
tree-shakable providers
advanced library DI patterns

This article explains the old Angular DI model, the modern model, and how everything fits together, then builds a complete application that uses these concepts in practice.

1. What Is Dependency Injection?

Before Angular, imagine this service:

export class UserService {
  getUser() {
    return {
      id: 1,
      name: 'Abanoub'
    };
  }
}

Now a component needs it.

A naive approach is:

export class UserComponent {

  private userService = new UserService();

}

This works, but it creates strong coupling.

The component decides:

which implementation to use
how the dependency is created
when it is created
how its dependencies are created

The component is doing too much.

Instead, we want:

export class UserComponent {

  constructor(private userService: UserService) {}

}

The component says:

"I need a UserService."

It does not say:

"I will create a UserService."

That distinction is the foundation of Dependency Injection.

Angular's DI system is responsible for providing dependencies to components, directives, services, functions, and other framework-managed code.

2. Dependency Injection vs Dependency Inversion

These concepts are related but not identical.

Dependency Injection

DI is a mechanism/pattern for supplying dependencies from outside a class.

constructor(private logger: LoggerService) {}

Dependency Inversion

Dependency Inversion is a broader architectural principle.

High-level modules should depend on abstractions rather than concrete implementations.

For example:

export abstract class PaymentGateway {
  abstract pay(amount: number): Promise<void>;
}

Then:

@Injectable()
export class StripePaymentGateway implements PaymentGateway {
  async pay(amount: number) {
    // Stripe implementation
  }
}

Angular DI can connect them:

providers: [
  {
    provide: PaymentGateway,
    useClass: StripePaymentGateway
  }
]

Now the application depends on:

PaymentGateway

rather than:

StripePaymentGateway

This is where Angular DI becomes an architectural tool rather than simply a convenience.

3. What Is a Dependency?

A dependency is anything a class needs to perform its job.

It doesn't have to be a service.

A dependency can be:

class

or:

object

or:

string

or:

number

or:

function

or:

configuration

For example:

class UserService {

  constructor(
    private http: HttpClient,
    private config: AppConfig
  ) {}

}

Both are dependencies.

Angular's DI system can provide services, values, functions, configuration objects, and other JavaScript values.

4. The Three Important DI Concepts

Most Angular DI problems become much easier once you understand these three terms:

Token
   ↓
Provider
   ↓
Injector

For example:

providers: [
  {
    provide: UserService,
    useClass: UserService
  }
]

Here:

Token

UserService

The token identifies what we want.

Provider

{
  provide: UserService,
  useClass: UserService
}

The provider tells Angular how to create or obtain it.

Injector

The injector stores provider information and resolves dependencies when requested.

Conceptually:

Component
    |
    | "Give me UserService"
    ↓
Injector
    |
    | finds provider
    ↓
Provider
    |
    | creates/returns instance
    ↓
UserService

5. The Old Angular DI Model

Before modern Angular patterns became common, you typically saw:

@Injectable({
  providedIn: 'root'
})
export class UserService {}

and:

@Component({
  selector: 'app-user',
  template: `...`
})
export class UserComponent {

  constructor(
    private userService: UserService
  ) {}

}

This is still valid.

It is not an obsolete API.

The major change is that Angular now gives developers another, often cleaner, way to inject dependencies.

6. Constructor Injection

The classic Angular DI syntax is constructor injection:

@Injectable({
  providedIn: 'root'
})
export class UserService {

  getUser() {
    return {
      id: 1,
      name: 'Abanoub'
    };
  }

}

Then:

@Component({
  selector: 'app-user',
  template: `
    <h1>{{ user.name }}</h1>
  `
})
export class UserComponent {

  constructor(
    private userService: UserService
  ) {}

  user = this.userService.getUser();

}

Angular sees:

UserService

and asks the DI system to resolve it.

Why constructor injection was popular

It has several advantages:

explicit dependencies
easy to understand
works naturally with TypeScript
dependencies are available when the class is created
excellent for traditional Angular codebases

But it also has limitations.

For example:

constructor(
  private http: HttpClient,
  private auth: AuthService,
  private router: Router,
  private logger: LoggerService,
  private config: ConfigService
) {}

Large constructors can become noisy.

There are also limitations around TypeScript's decorator metadata and modern standard decorators.

Angular therefore introduced the inject() API as a modern alternative. Angular's migration tooling can convert constructor-based injection to inject().

7. Modern Angular DI: `inject()`

Today you will frequently see:

import { Component, inject } from '@angular/core';

@Component({
  selector: 'app-user',
  template: `...`
})
export class UserComponent {

  private userService = inject(UserService);

}

This is dependency injection too.

Angular resolves:

UserService

from the currently active injector.

The important thing is:

inject(UserService)

does not mean:

new UserService()

Angular still controls the dependency lifecycle and provider resolution.

The inject() function is supported in injection contexts such as constructors, field initializers, provider factories, and other framework-managed DI contexts.

8. Constructor Injection vs `inject()`

Old style

export class DashboardComponent {

  constructor(
    private userService: UserService,
    private router: Router
  ) {}

}

Modern style

export class DashboardComponent {

  private userService = inject(UserService);
  private router = inject(Router);

}

Both are valid.

A practical modern Angular style is:

private userService = inject(UserService);
private router = inject(Router);

because dependencies are declared close to where they are used and TypeScript can infer types naturally.

However, constructor injection remains perfectly legitimate, especially in existing applications and when working with patterns that depend on constructor parameters. Angular's own guidance explicitly supports both approaches.

9. The Injection Context

This is one of the most important modern Angular DI concepts.

You cannot call:

inject(UserService)

anywhere.

This is invalid:

export class UserComponent {

  ngOnInit() {

    const service = inject(UserService); // ❌

  }

}

Why?

Because ngOnInit() executes after the object has already been created.

Angular's DI context is available during class creation/initialization and specific framework-managed contexts, not arbitrary later callbacks.

10. Valid Places for `inject()`

Field initializer

export class UserComponent {

  private userService = inject(UserService);

}

Constructor

export class UserComponent {

  constructor() {

    const service = inject(UserService);

  }

}

Provider factory

{
  provide: UserService,
  useFactory: () => {

    const logger = inject(LoggerService);

    return new UserService(logger);

  }
}

InjectionToken factory

const API_URL = new InjectionToken<string>(
  'API_URL',
  {
    providedIn: 'root',

    factory: () => {

      const config = inject(AppConfig);

      return config.apiUrl;

    }
  }
);

Functional route guard

export const authGuard = () => {

  const auth = inject(AuthService);

  return auth.isAuthenticated();

};

Angular documents functional guards and similar framework APIs as injection contexts.

11. Why `inject()` Fails in Async Code

This is a common mistake:

async loadUser() {

  await delay(1000);

  const userService = inject(UserService); // ❌

}

After the await, you are no longer inside the original synchronous injection context.

Instead:

private userService = inject(UserService);

async loadUser() {

  await delay(1000);

  this.userService.getUser();

}

Capture dependencies while you are inside the injection context.

12. `runInInjectionContext()`

Sometimes you genuinely need to execute a function inside an injection context.

Angular provides:

runInInjectionContext()

Example:

import {
  EnvironmentInjector,
  inject,
  runInInjectionContext
} from '@angular/core';

@Injectable({
  providedIn: 'root'
})
export class DynamicService {

  private injector = inject(EnvironmentInjector);

  execute() {

    runInInjectionContext(
      this.injector,
      () => {

        const logger = inject(LoggerService);

        logger.log('Hello');

      }
    );

  }

}

This creates a temporary injection context for the callback.

Use this when you actually need dynamic DI.

Do not use it as a replacement for normal injection.

13. `Injector`

Angular also exposes the injector itself.

private injector = inject(Injector);

You can then resolve dependencies manually:

const service = this.injector.get(UserService);

This can be useful when the dependency needs to be resolved later.

For example:

private injector = inject(Injector);

loadLater() {

  setTimeout(() => {

    const userService =
      this.injector.get(UserService);

    userService.getUser();

  }, 1000);

}

Angular's debugging guidance recommends capturing dependencies normally where possible and using Injector.get() for deferred retrieval when necessary.

14. `@Injectable()`

The classic way to declare an injectable service is:

@Injectable()
export class UserService {}

However, this alone doesn't necessarily make the service globally available.

You need a provider.

For example:

@Component({
  providers: [
    UserService
  ]
})
export class UserComponent {}

Or:

bootstrapApplication(AppComponent, {
  providers: [
    UserService
  ]
});

15. `providedIn`

The most common modern approach is:

@Injectable({
  providedIn: 'root'
})
export class UserService {}

This tells Angular that the service belongs to the root injector.

It is also tree-shakable.

That means Angular's build system can remove unused injectable definitions from the final bundle when they are not referenced.

For most application-wide services:

@Injectable({
  providedIn: 'root'
})

is the default choice.

16. `providedIn: 'root'`

@Injectable({
  providedIn: 'root'
})
export class AuthService {}

This normally gives the application a single instance associated with the root environment injector.

Every component requesting:

inject(AuthService)

will resolve the same root-scoped instance unless a closer provider overrides it.

17. `providedIn: 'platform'`

Historically Angular also supported:

@Injectable({
  providedIn: 'platform'
})

This places the service in the platform-level injector rather than the application root.

It is useful for special scenarios involving multiple Angular applications sharing a platform.

It is not something you should use by default.

18. The Historical `providedIn: 'any'`

Older Angular versions supported:

providedIn: 'any'

This had special behavior with lazy-loaded injectors.

Modern Angular documentation marks 'any' as deprecated.

So if you see:

providedIn: 'any'

in older code, understand what it does before changing it, but don't treat it as the preferred modern pattern.

19. `providedIn: NgModule`

You may also encounter:

@Injectable({
  providedIn: SomeModule
})

This belongs to the older NgModule-oriented DI model.

The modern Angular architecture favors environment providers and standalone APIs.

Angular's current documentation marks providedIn: NgModule as deprecated for InjectionToken configuration, and modern applications generally prefer environment-based provider configuration.

20. Manual Providers

Instead of:

@Injectable({
  providedIn: 'root'
})
export class UserService {}

you can manually provide:

providers: [
  UserService
]

For example:

@Component({
  selector: 'app-profile',
  providers: [
    UserService
  ],
  template: `...`
})
export class ProfileComponent {}

Now the service belongs to this component's injector.

21. Component-Level Providers

This is extremely important.

Consider:

@Component({
  providers: [
    CounterService
  ]
})
export class CounterComponent {

  private counter = inject(CounterService);

}

Every instance of CounterComponent gets its own CounterService.

For example:

<app-counter></app-counter>
<app-counter></app-counter>

Conceptually:

CounterComponent #1
   |
   └── CounterService #1

CounterComponent #2
   |
   └── CounterService #2

This is completely different from:

@Injectable({
  providedIn: 'root'
})

where both components normally resolve the same root instance.

Angular's component providers configure the component's ElementInjector, and that instance is destroyed with the component.

22. The Provider Shorthand

This:

providers: [
  UserService
]

is effectively a shorthand for:

providers: [
  {
    provide: UserService,
    useClass: UserService
  }
]

This leads us to one of the most important DI concepts:

Provider Recipes

Angular supports several provider strategies.

23. `useClass`

providers: [
  {
    provide: LoggerService,
    useClass: ConsoleLoggerService
  }
]

Whenever something asks for:

LoggerService

Angular creates:

ConsoleLoggerService

This is extremely useful for abstraction.

For example:

abstract class PaymentGateway {

  abstract pay(amount: number): Promise<void>;

}

Production:

providers: [
  {
    provide: PaymentGateway,
    useClass: StripePaymentGateway
  }
]

Testing:

providers: [
  {
    provide: PaymentGateway,
    useClass: FakePaymentGateway
  }
]

The consumer doesn't change.

24. `useValue`

Sometimes you don't need Angular to create an object.

You already have the value.

Use:

useValue

Example:

export const API_URL =
  new InjectionToken<string>('API_URL');

bootstrapApplication(AppComponent, {

  providers: [
    {
      provide: API_URL,
      useValue: 'https://api.example.com'
    }
  ]

});

Then:

export class ApiService {

  private apiUrl = inject(API_URL);

}

useValue can provide strings, numbers, objects, arrays, functions, configuration, and other static values.

25. Why You Need `InjectionToken`

This won't work:

export interface AppConfig {
  apiUrl: string;
}

and:

constructor(private config: AppConfig) {}

Why?

Because interfaces disappear during TypeScript compilation.

At runtime:

AppConfig

doesn't exist.

Angular needs a runtime token.

That's what InjectionToken provides.

26. `InjectionToken`

export interface AppConfig {

  apiUrl: string;
  production: boolean;

}

export const APP_CONFIG =
  new InjectionToken<AppConfig>('APP_CONFIG');

Provide:

providers: [
  {
    provide: APP_CONFIG,

    useValue: {
      apiUrl: 'https://api.example.com',
      production: false
    }
  }
]

Inject:

private config = inject(APP_CONFIG);

Now:

this.config.apiUrl

is strongly typed.

Angular recommends InjectionToken for dependencies that do not have a runtime representation, such as interfaces, functions, arrays, and parameterized types.

27. InjectionToken Identity Matters

This is a subtle but important bug.

Don't do this:

const API_URL =
  new InjectionToken<string>('API_URL');

in one file and:

const API_URL =
  new InjectionToken<string>('API_URL');

in another.

Even though the names are identical, these are two different objects.

Angular compares token identity, not the description string.

Always export one token:

export const API_URL =
  new InjectionToken<string>('API_URL');

and import that same token everywhere.

28. `useFactory`

Factories are useful when the dependency must be dynamically constructed.

Example:

export const API_CLIENT_PROVIDER = {

  provide: ApiClient,

  useFactory: () => {

    const http = inject(HttpClient);
    const config = inject(APP_CONFIG);

    return new ApiClient(
      http,
      config.apiUrl
    );

  }

};

Now Angular executes the factory when it needs the dependency.

Factories are excellent for:

runtime configuration
environment-dependent implementations
complex initialization
combining multiple dependencies
library configuration

Angular supports both useFactory providers and factory-based injection tokens.

29. Factory Dependencies with `deps`

The older explicit style is:

{
  provide: ApiClient,

  useFactory: (
    http: HttpClient,
    config: AppConfig
  ) => {

    return new ApiClient(
      http,
      config.apiUrl
    );

  },

  deps: [
    HttpClient,
    APP_CONFIG
  ]
}

Modern Angular code can often use inject() directly inside the factory:

{
  provide: ApiClient,

  useFactory: () => {

    const http = inject(HttpClient);
    const config = inject(APP_CONFIG);

    return new ApiClient(
      http,
      config.apiUrl
    );

  }
}

30. `useExisting`

This is one of the most misunderstood provider types.

Suppose:

class NewLogger {}

class OldLogger {}

You can alias:

providers: [
  NewLogger,

  {
    provide: OldLogger,
    useExisting: NewLogger
  }
]

Now:

inject(NewLogger)

and:

inject(OldLogger)

return the same instance.

31. `useExisting` vs `useClass`

This distinction matters.

`useClass`

{
  provide: Logger,
  useClass: ConsoleLogger
}

Angular creates an instance of:

ConsoleLogger

`useExisting`

{
  provide: LegacyLogger,
  useExisting: ConsoleLogger
}

Angular returns the already-existing ConsoleLogger instance.

Conceptually:

useClass

Logger ───────> ConsoleLogger #1


useExisting

Logger ───────┐
              ├──> ConsoleLogger #1
LegacyLogger ─┘

Angular's documentation explicitly distinguishes these behaviors.

32. `multi: true`

Sometimes you don't want one implementation.

You want many.

For example:

export const LOG_HANDLERS =
  new InjectionToken<LogHandler[]>(
    'LOG_HANDLERS'
  );

Then:

providers: [

  {
    provide: LOG_HANDLERS,
    useClass: ConsoleLogHandler,
    multi: true
  },

  {
    provide: LOG_HANDLERS,
    useClass: RemoteLogHandler,
    multi: true
  },

  {
    provide: LOG_HANDLERS,
    useClass: AnalyticsLogHandler,
    multi: true
  }

]

Now:

private handlers = inject(LOG_HANDLERS);

returns an array.

LOG_HANDLERS
     |
     ├── ConsoleLogHandler
     ├── RemoteLogHandler
     └── AnalyticsLogHandler

This pattern is heavily used in extensible Angular architecture.

33. `providers` vs `viewProviders`

These look similar:

providers

and:

viewProviders

but they have an important difference.

Consider:

<app-parent>

  <app-child />

</app-parent>

and:

<app-parent>

  <ng-content />

</app-parent>

providers can be visible to projected content.

viewProviders restricts the provider to the component's own view.

Example:

@Component({
  providers: [
    ThemeService
  ]
})

The service can be available to projected content.

But:

@Component({
  viewProviders: [
    ThemeService
  ]
})

keeps it within the component's own view.

Angular recommends providers by default unless you specifically need the isolation behavior of viewProviders.

34. Angular's Injector Hierarchy

This is where Angular DI becomes really powerful.

Modern Angular has two major injector hierarchies:

EnvironmentInjector hierarchy

        Root
         |
    Environment
         |
    Feature / Route

and:

ElementInjector hierarchy

Component
   |
Child Component
   |
Grandchild Component

Angular documents these as the EnvironmentInjector and ElementInjector hierarchies.

35. EnvironmentInjector

The EnvironmentInjector is used for application/environment-level providers.

For example:

bootstrapApplication(AppComponent, {
  providers: [
    UserService
  ]
});

Or:

@Injectable({
  providedIn: 'root'
})
export class AuthService {}

These belong to the environment hierarchy.

This is the modern standalone Angular replacement for many things developers historically configured through NgModule.providers.

36. ElementInjector

Angular also creates an injector associated with elements/components.

For example:

@Component({
  providers: [
    CounterService
  ]
})
export class CounterComponent {}

This configures the component's ElementInjector.

Angular creates these element-level injectors implicitly, and they are empty unless providers are configured on components or directives.

37. How Angular Resolves a Dependency

Suppose:

@Component({
  providers: [
    UserService
  ]
})
export class ChildComponent {

  private user = inject(UserService);

}

Angular roughly searches:

Child ElementInjector
        ↓
Parent ElementInjector
        ↓
Ancestor ElementInjectors
        ↓
EnvironmentInjector hierarchy
        ↓
Root

The important rule is:

Angular uses the closest matching provider.

If a child defines its own provider, it can override the parent.

Angular's documented resolution process first walks the relevant element injector hierarchy and then falls back to the environment hierarchy.

38. Provider Override

Imagine:

@Injectable({
  providedIn: 'root'
})
export class LoggerService {

  name = 'Global Logger';

}

Then:

@Component({
  providers: [
    {
      provide: LoggerService,
      useValue: {
        name: 'Local Logger'
      }
    }
  ]
})
export class FeatureComponent {}

Inside:

FeatureComponent

you get:

Local Logger

while another component outside that subtree still gets:

Global Logger

This is dependency scoping.

39. `Self`

Sometimes you want Angular to search only the current injector.

With inject():

inject(UserService, {
  self: true
});

Conceptually:

Current Injector
      |
      X
Parent
      |
      X
Root

If the dependency isn't available locally, Angular fails.

This is useful when you explicitly require a local provider.

40. `SkipSelf`

skipSelf does the opposite.

inject(UserService, {
  skipSelf: true
});

Angular skips the current injector and starts searching from the parent.

Conceptually:

Current Injector  ← skipped

Parent Injector   ← start here
       ↓
Grandparent
       ↓
Root

This is useful when a child provider overrides a parent provider but you specifically need the parent instance.

41. `Optional`

Sometimes a dependency is optional.

Instead of throwing an error:

inject(AnalyticsService);

use:

inject(AnalyticsService, {
  optional: true
});

Now Angular can return:

null

if the provider doesn't exist.

Example:

private analytics =
  inject(AnalyticsService, {
    optional: true
  });

track() {

  this.analytics?.track('click');

}

42. `Host`

host limits the DI search according to the host boundary.

inject(UserService, {
  host: true
});

This becomes particularly important with:

component boundaries
directives
viewProviders
content projection

It is an advanced DI modifier and should be used when you actually need control over the resolution boundary. Angular's hierarchical DI documentation provides detailed examples of how host, skipSelf, and viewProviders interact.

43. Combining DI Modifiers

You can combine options.

For example:

inject(UserService, {
  skipSelf: true,
  optional: true
});

Meaning roughly:

"Don't use the current injector. Search the parents, but don't throw if nothing is found."

You can also use:

inject(UserService, {
  host: true,
  skipSelf: true,
  optional: true
});

These combinations become useful in advanced component/library architectures.

44. The Old Decorator Modifiers

In constructor injection, you may see:

constructor(
  @Optional()
  private analytics: AnalyticsService
) {}

or:

constructor(
  @Self()
  private service: LocalService
) {}

or:

constructor(
  @SkipSelf()
  private service: ParentService
) {}

or:

constructor(
  @Host()
  private service: HostService
) {}

You may also see:

@Inject(TOKEN)

These are older constructor-oriented APIs.

Modern inject() expresses the same concepts through options:

inject(TOKEN, {
  optional: true
});

45. `@Inject()`

Suppose the dependency isn't represented by a class:

export const API_URL =
  new InjectionToken<string>('API_URL');

Old style:

constructor(
  @Inject(API_URL)
  private apiUrl: string
) {}

Modern:

private apiUrl = inject(API_URL);

The modern syntax is usually much cleaner.

46. `forwardRef()`

Sometimes Angular needs to reference something before the TypeScript runtime declaration is available.

Example:

@Component({
  providers: [
    {
      provide: ParentComponent,
      useExisting: forwardRef(
        () => ChildComponent
      )
    }
  ]
})
export class ChildComponent {}

forwardRef() allows Angular to resolve a reference later.

It is mostly useful for circular references and unusual declaration-order scenarios.

Angular documents forwardRef() specifically for resolving references that cannot yet be directly referenced because of declaration order or circular relationships.

47. NgModule-Based DI

Older Angular applications commonly looked like:

@NgModule({
  declarations: [
    AppComponent
  ],

  imports: [
    BrowserModule
  ],

  providers: [
    UserService
  ],

  bootstrap: [
    AppComponent
  ]
})
export class AppModule {}

The application started with:

platformBrowserDynamic()
  .bootstrapModule(AppModule);

This architecture is still supported.

But modern Angular applications increasingly use:

bootstrapApplication()

with standalone components and environment providers.

48. Modern Standalone DI

Modern Angular:

bootstrapApplication(
  AppComponent,
  {
    providers: [
      UserService
    ]
  }
);

You can also use Angular's provider functions:

bootstrapApplication(
  AppComponent,
  {
    providers: [
      provideRouter(routes),
      provideHttpClient()
    ]
  }
);

This is one of the biggest architectural changes from the older NgModule era.

49. Provider Functions

Modern Angular libraries frequently expose APIs such as:

provideRouter(...)

and:

provideHttpClient(...)

Instead of asking developers to manually understand dozens of providers, the library exposes a single configuration function.

You can build the same pattern yourself.

Example:

export interface AnalyticsConfig {
  trackingId: string;
}

const ANALYTICS_CONFIG =
  new InjectionToken<AnalyticsConfig>(
    'ANALYTICS_CONFIG'
  );

export function provideAnalytics(
  config: AnalyticsConfig
) {

  return [
    {
      provide: ANALYTICS_CONFIG,
      useValue: config
    },

    AnalyticsService
  ];

}

Consumer:

bootstrapApplication(AppComponent, {

  providers: [
    provideAnalytics({
      trackingId: 'GA-123'
    })
  ]

});

This provideX() pattern is especially useful for Angular libraries because it encapsulates implementation details and makes configuration composable.

50. Feature Functions: `withX()`

Modern Angular libraries also use patterns such as:

provideSomething(
  withCaching(),
  withLogging(),
  withRetry()
)

You can implement the same architecture.

Example:

export function withLogging(): AnalyticsFeature {

  return {
    providers: [
      LoggingAnalyticsHandler
    ]
  };

}

Then:

provideAnalytics(
  config,
  withLogging()
);

This gives libraries a clean, composable API.

51. `InjectionToken` with a Factory

An InjectionToken can provide its own factory.

Example:

export const API_URL =
  new InjectionToken<string>(
    'API_URL',
    {
      providedIn: 'root',

      factory: () => {
        return 'https://api.example.com';
      }
    }
  );

Now you don't need:

providers: [
  {
    provide: API_URL,
    useValue: ...
  }
]

The token knows how to create itself.

This is another tree-shakable DI pattern.

52. DI and Testing

One of the biggest reasons DI exists is testability.

Without DI:

class UserService {

  private api =
    new RealApiClient();

}

Testing becomes difficult.

With DI:

class UserService {

  private api =
    inject(ApiClient);

}

Test:

TestBed.configureTestingModule({

  providers: [

    UserService,

    {
      provide: ApiClient,

      useClass: FakeApiClient
    }

  ]

});

Now the real API doesn't need to be called.

This is Dependency Injection's architectural value.

53. DI and Mocking

Suppose:

export abstract class PaymentGateway {

  abstract pay(
    amount: number
  ): Promise<boolean>;

}

Production:

{
  provide: PaymentGateway,
  useClass: StripePaymentGateway
}

Testing:

{
  provide: PaymentGateway,
  useClass: FakePaymentGateway
}

Your business logic doesn't know which implementation it received.

That's dependency inversion + DI.

54. DI and SOLID

Angular DI strongly supports SOLID principles.

Single Responsibility

A component doesn't need to create its dependencies.

Open/Closed

You can replace implementations without modifying consumers.

Liskov Substitution

Abstractions can be backed by interchangeable implementations.

Interface Segregation

Smaller tokens/interfaces can define focused contracts.

Dependency Inversion

High-level services can depend on abstractions.

DI doesn't automatically make an architecture SOLID, but it provides an excellent mechanism for implementing these principles.

55. DI Is Not a Global Singleton System

This is a common misconception.

People often say:

"Angular services are singletons."

That's not always true.

Consider:

@Injectable({
  providedIn: 'root'
})
export class CartService {}

This is normally application-wide.

But:

@Component({
  providers: [
    CartService
  ]
})
export class CheckoutComponent {}

creates a different scoped instance.

You can therefore have:

Root CartService
        |
        ├── Component A → root instance
        |
        └── Checkout → local instance

Angular DI is fundamentally about scope and resolution, not simply singletons.

56. Service Lifetime

Where you provide a dependency influences its lifetime.

Root provider

providedIn: 'root'

Usually lives for the application lifetime.

Component provider

@Component({
  providers: [CartService]
})

Lives with that component's injector.

When the component is destroyed, its scoped service can be destroyed as well.

This makes component-level DI extremely useful for isolated state.

57. A Perfect Use Case: Local Component State

Imagine:

@Injectable()
export class WizardState {

  currentStep = 1;

  next() {
    this.currentStep++;
  }

}

Then:

@Component({
  selector: 'app-checkout-wizard',

  providers: [
    WizardState
  ],

  template: `...`
})
export class CheckoutWizard {

  state = inject(WizardState);

}

Now every checkout wizard gets independent state.

You don't need:

WizardState #1
WizardState #2
WizardState #3

manually.

Angular's injector gives you the correct scoped instance.

58. Route-Level Providers

Modern Angular also allows providers to be associated with routes.

Conceptually:

export const routes: Routes = [

  {
    path: 'admin',

    providers: [
      AdminService
    ],

    loadComponent: () =>
      import('./admin.component')
        .then(m => m.AdminComponent)
  }

];

This is powerful because you can scope dependencies to a feature.

For example:

Application
   |
   ├── Public area
   |
   └── Admin route
          |
          └── AdminService

The admin dependency doesn't have to become globally available.

59. DI in Functional Guards

Older Angular:

@Injectable()
export class AuthGuard
  implements CanActivate {

  constructor(
    private auth: AuthService
  ) {}

  canActivate() {
    return this.auth.isAuthenticated();
  }

}

Modern Angular can use:

export const authGuard: CanActivateFn = () => {

  const auth =
    inject(AuthService);

  return auth.isAuthenticated();

};

This is a great example of how inject() enables functional Angular APIs.

60. DI in Functional Resolvers

The same principle applies to resolvers:

export const userResolver: ResolveFn<User> =
  () => {

    const userService =
      inject(UserService);

    return userService.getCurrentUser();

  };

No class is required.

Angular supplies the injection context.

61. DI and Directives

DI isn't only for components.

@Directive({
  selector: '[appHighlight]'
})
export class HighlightDirective {

  private element =
    inject(ElementRef);

}

Angular can inject framework-provided tokens such as:

ElementRef

and application services.

Angular documents DI as available to directives and components because they participate in the Angular DI system.

62. DI and Pipes

Injectable dependencies can also be used in pipes.

For example:

@Pipe({
  name: 'currencyFormat'
})
export class CurrencyFormatPipe {

  private config =
    inject(AppConfig);

  transform(value: number) {

    return `${this.config.currency}${value}`;

  }

}

63. DI and Interceptors

Modern functional interceptors are another excellent example:

export const authInterceptor:
  HttpInterceptorFn = (req, next) => {

    const auth =
      inject(AuthService);

    const token =
      auth.getToken();

    return next(
      req.clone({
        setHeaders: {
          Authorization: `Bearer ${token}`
        }
      })
    );

  };

The function itself doesn't receive AuthService as a parameter.

Angular creates the injection context in which the interceptor runs.

64. DI and Environment Configuration

A professional Angular application often needs:

API_URL

APP_NAME

FEATURE_FLAGS

DEFAULT_PAGE_SIZE

Instead of hardcoding these everywhere, define tokens.

export interface AppConfig {

  apiUrl: string;

  appName: string;

  features: {
    analytics: boolean;
    darkMode: boolean;
  };

}

Then:

export const APP_CONFIG =
  new InjectionToken<AppConfig>(
    'APP_CONFIG'
  );

Provide it once:

bootstrapApplication(AppComponent, {

  providers: [

    {
      provide: APP_CONFIG,

      useValue: {
        apiUrl: 'https://api.example.com',
        appName: 'Task Manager',

        features: {
          analytics: true,
          darkMode: true
        }
      }

    }

  ]

});

Now every service can consume strongly typed configuration.

65. Complete Project: Task Management Application

Let's build a realistic Angular architecture that demonstrates DI from beginning to end.

Our application will contain:

Task Management App

├── Configuration
├── Authentication
├── Logging
├── API Client
├── Task Repository
├── Task Service
├── Feature-specific providers
├── Payment abstraction
└── Testing implementation

66. Project Structure

src/
└── app/

    ├── core/
    │   ├── config/
    │   │   └── app-config.ts
    │   │
    │   ├── logging/
    │   │   ├── logger.ts
    │   │   └── console-logger.ts
    │   │
    │   ├── auth/
    │   │   └── auth.service.ts
    │   │
    │   └── api/
    │       └── api-client.ts
    │
    ├── tasks/
    │   ├── task.model.ts
    │   ├── task.repository.ts
    │   ├── task.service.ts
    │   └── task-list.component.ts
    │
    ├── app.component.ts
    ├── app.config.ts
    └── main.ts

67. Application Configuration

Create:

// core/config/app-config.ts

import { InjectionToken } from '@angular/core';

export interface AppConfig {

  apiUrl: string;

  appName: string;

  features: {
    analytics: boolean;
  };

}

export const APP_CONFIG =
  new InjectionToken<AppConfig>(
    'APP_CONFIG'
  );

68. Provide Configuration

// app.config.ts

import {
  ApplicationConfig
} from '@angular/core';

import {
  APP_CONFIG
} from './core/config/app-config';

export const appConfig:
  ApplicationConfig = {

  providers: [

    {
      provide: APP_CONFIG,

      useValue: {
        apiUrl: 'https://api.example.com',

        appName: 'Task Manager',

        features: {
          analytics: true
        }
      }
    }

  ]

};

69. Logger Abstraction

Create:

// core/logging/logger.ts

export abstract class Logger {

  abstract info(
    message: string
  ): void;

  abstract error(
    message: string
  ): void;

}

Now the application depends on:

Logger

not:

ConsoleLogger

70. Logger Implementation

// core/logging/console-logger.ts

import { Injectable } from '@angular/core';

import {
  Logger
} from './logger';

@Injectable()
export class ConsoleLogger
  implements Logger {

  info(message: string) {

    console.log(
      `[INFO] ${message}`
    );

  }

  error(message: string) {

    console.error(
      `[ERROR] ${message}`
    );

  }

}

71. Connect the Abstraction

In app.config.ts:

providers: [

  {
    provide: Logger,
    useClass: ConsoleLogger
  }

]

Now:

inject(Logger)

returns:

ConsoleLogger

The consumer doesn't care about the implementation.

72. Authentication Service

@Injectable({
  providedIn: 'root'
})
export class AuthService {

  private token =
    'fake-jwt-token';

  isAuthenticated(): boolean {

    return !!this.token;

  }

  getToken(): string {

    return this.token;

  }

}

Because it is root-provided, the application can share the service.

73. API Client

@Injectable({
  providedIn: 'root'
})
export class ApiClient {

  private http =
    inject(HttpClient);

  private config =
    inject(APP_CONFIG);

  get<T>(path: string) {

    return this.http.get<T>(
      `${this.config.apiUrl}${path}`
    );

  }

}

Now this service demonstrates DI with:

ApiClient
   |
   ├── HttpClient
   |
   └── APP_CONFIG

Angular constructs the dependency graph.

74. Task Repository

Define:

export abstract class TaskRepository {

  abstract getTasks():
    Observable<Task[]>;

}

Production implementation:

@Injectable()
export class HttpTaskRepository
  implements TaskRepository {

  private api =
    inject(ApiClient);

  getTasks() {

    return this.api.get<Task[]>(
      '/tasks'
    );

  }

}

75. Connect Repository to DI

providers: [

  {
    provide: TaskRepository,

    useClass: HttpTaskRepository
  }

]

Now:

inject(TaskRepository)

returns:

HttpTaskRepository

This is dependency inversion in practice.

76. Task Service

@Injectable({
  providedIn: 'root'
})
export class TaskService {

  private repository =
    inject(TaskRepository);

  getTasks() {

    return this.repository.getTasks();

  }

}

Notice the architecture:

TaskService
     |
     ↓
TaskRepository
     |
     ↓
HttpTaskRepository
     |
     ↓
ApiClient
     |
     ↓
HttpClient

The TaskService does not know how HTTP works.

That's good architecture.

77. Component

@Component({
  selector: 'app-task-list',

  template: `

    <h1>Tasks</h1>

    @for (task of tasks(); track task.id) {

      <article>

        <h2>{{ task.title }}</h2>

        <p>{{ task.description }}</p>

      </article>

    }

  `
})
export class TaskListComponent {

  private taskService =
    inject(TaskService);

  tasks = signal<Task[]>([]);

  constructor() {

    this.taskService
      .getTasks()
      .subscribe(tasks => {

        this.tasks.set(tasks);

      });

  }

}

Now the component doesn't know anything about:

HTTP
URLs
authentication
repositories
configuration

It only knows:

TaskService

That's exactly what DI should help you achieve.

78. Full Dependency Graph

The final graph looks like:

                    AppConfig
                       │
                       ↓
HttpClient ───────→ ApiClient
                       │
                       ↓
              HttpTaskRepository
                       │
                       ↓
                TaskRepository
                       │
                       ↓
                  TaskService
                       │
                       ↓
                TaskListComponent

Angular's DI system resolves this graph.

You don't manually write:

new ApiClient(...)
new HttpTaskRepository(...)
new TaskService(...)

Angular handles construction and provider resolution.

79. Replacing the Repository

Imagine tomorrow you replace REST with GraphQL.

Create:

@Injectable()
export class GraphQLTaskRepository
  implements TaskRepository {

  getTasks() {

    // GraphQL implementation

  }

}

Change the provider:

{
  provide: TaskRepository,

  useClass:
    GraphQLTaskRepository
}

The following code doesn't change:

TaskService

or:

TaskListComponent

That's the real power of abstraction + DI.

80. Adding a Fake Repository for Testing

@Injectable()
export class FakeTaskRepository
  implements TaskRepository {

  getTasks() {

    return of([
      {
        id: 1,
        title: 'Learn Angular DI',
        description:
          'Understand providers and injectors'
      }
    ]);

  }

}

Test configuration:

providers: [

  {
    provide: TaskRepository,

    useClass:
      FakeTaskRepository
  }

]

Now the entire application can run without a backend.

81. Factory-Based API Client

Suppose development and production require different API clients.

You can create:

export const API_CLIENT_PROVIDER = {

  provide: ApiClient,

  useFactory: () => {

    const http =
      inject(HttpClient);

    const config =
      inject(APP_CONFIG);

    const logger =
      inject(Logger);

    return new ApiClient(
      http,
      config,
      logger
    );

  }

};

This is useful when object construction requires multiple dependencies or runtime decisions.

82. Multiple Log Handlers

Let's make logging extensible.

export const LOG_HANDLERS =
  new InjectionToken<LogHandler[]>(
    'LOG_HANDLERS'
  );

Provide:

providers: [

  {
    provide: LOG_HANDLERS,
    useClass: ConsoleLogHandler,
    multi: true
  },

  {
    provide: LOG_HANDLERS,
    useClass: RemoteLogHandler,
    multi: true
  }

]

Then:

@Injectable({
  providedIn: 'root'
})
export class LoggerService {

  private handlers =
    inject(LOG_HANDLERS);

  info(message: string) {

    for (const handler
      of this.handlers) {

      handler.info(message);

    }

  }

}

Now adding another logging destination requires adding another provider rather than changing LoggerService.

83. Building a `provideTasks()` API

We can package the entire feature.

export function provideTasks(): Provider[] {

  return [

    {
      provide: TaskRepository,

      useClass:
        HttpTaskRepository
    },

    TaskService

  ];

}

Then:

bootstrapApplication(
  AppComponent,
  {
    providers: [
      provideTasks()
    ]
  }
);

For a real library, you would typically return an appropriate provider configuration and may compose optional features.

This is the same architectural idea behind Angular's provider-function APIs.

84. Advanced `provideX()` Architecture

A more sophisticated API can look like:

provideTasks(
  withCaching(),
  withLogging(),
  withRetry()
)

Internally:

export function provideTasks(
  ...features: TaskFeature[]
): Provider[] {

  return [

    TaskService,

    ...features.flatMap(
      feature => feature.providers
    )

  ];

}

This pattern is excellent for reusable Angular libraries.

85. `viewProviders` in Real Applications

Consider a reusable component:

@Component({
  selector: 'app-data-table',

  viewProviders: [
    TableState
  ],

  template: `
    <table>
      ...
    </table>

    <ng-content />
  `
})
export class DataTableComponent {}

If TableState is an internal implementation detail, viewProviders can prevent projected content from accidentally depending on it.

This is a real architectural reason to use viewProviders.

86. Lightweight Injection Tokens

Angular libraries sometimes want a parent component to communicate with a child without forcing a hard runtime dependency on the concrete component class.

For example:

export abstract class HeaderToken {

  abstract close(): void;

}

Then:

@Component({
  selector: 'app-header',

  providers: [
    {
      provide: HeaderToken,
      useExisting: HeaderComponent
    }
  ]
})
export class HeaderComponent
  extends HeaderToken {

  close() {
    // ...
  }

}

Consumers depend on:

HeaderToken

instead of:

HeaderComponent

Angular documents this as a lightweight injection-token pattern useful for library design and tree-shaking.

87. DI and Circular Dependencies

Sometimes you accidentally create:

A → B
↑   ↓
└───┘

For example:

ServiceA → ServiceB
ServiceB → ServiceA

This can produce DI errors.

The correct solution is usually architectural:

remove the circular dependency
introduce an abstraction
move shared behavior to another service
restructure the dependency graph

Don't immediately reach for forwardRef().

forwardRef() solves declaration/reference problems; it is not a general solution for bad architecture.

88. Common DI Error: NullInjectorError

You may see:

NullInjectorError:
No provider for UserService!

Usually this means:

inject(UserService)

was called but Angular couldn't find a provider in the available injector hierarchy.

Possible solutions:

@Injectable({
  providedIn: 'root'
})

or:

providers: [
  UserService
]

or:

bootstrapApplication(AppComponent, {
  providers: [
    UserService
  ]
});

But don't blindly add:

providedIn: 'root'

just to make the error disappear.

First determine the intended scope.

89. Common DI Error: Wrong Scope

Suppose:

@Component({
  providers: [
    CartService
  ]
})
export class CheckoutComponent {}

Then another unrelated parent tries:

inject(CartService)

and fails.

Why?

Because the service exists inside the checkout component's injector, not globally.

The solution isn't necessarily moving it to root.

The real question is:

Where should this dependency live?

That's the architectural question DI forces you to answer.

90. Common Error: `inject()` Outside Context

This:

ngOnInit() {

  const service =
    inject(UserService);

}

causes:

NG0203

because ngOnInit() is not an injection context.

Fix:

private service =
  inject(UserService);

Then:

ngOnInit() {

  this.service.load();

}

Angular explicitly documents NG0203 as the error produced when inject() is used outside a valid injection context.

91. Common Error: Two InjectionTokens

Wrong:

const CONFIG =
  new InjectionToken<AppConfig>(
    'CONFIG'
  );

Provider file:

const CONFIG =
  new InjectionToken<AppConfig>(
    'CONFIG'
  );

These are different tokens.

Correct:

// config.token.ts

export const CONFIG =
  new InjectionToken<AppConfig>(
    'CONFIG'
  );

Then:

import { CONFIG }
  from './config.token';

everywhere.

92. Common Error: Confusing `useClass` and `useExisting`

If you want:

same instance

use:

useExisting

If you want Angular to create an implementation from a class:

useClass

Remember:

useClass    → implementation
useExisting → alias

93. Common Error: Making Everything `providedIn: 'root'`

This is probably the most common architectural mistake.

Developers write:

@Injectable({
  providedIn: 'root'
})

for every service.

But some services should be scoped:

@Component({
  providers: [
    FormStateService
  ]
})

Others may belong to:

feature
route
environment
application
component

A good Angular architecture chooses scope intentionally.

94. How to Decide Provider Scope

Ask:

Should every part of the application share one instance?

Use:

providedIn: 'root'

Should every instance of a component have independent state?

Use:

@Component({
  providers: [...]
})

Should a feature have its own dependency?

Consider route/environment providers.

Should the dependency be configurable?

Use:

InjectionToken

Should different implementations be interchangeable?

Use:

abstract class / InjectionToken
+
useClass

Should multiple implementations contribute?

Use:

multi: true

Should an existing provider be exposed under another token?

Use:

useExisting

Does creation require runtime logic?

Use:

useFactory

95. DI in Modern Angular vs Old Angular

Concept	Traditional Angular	Modern Angular
Injection	Constructor	`inject()` + constructor
Application architecture	NgModules	Standalone
Global providers	`AppModule.providers`	`ApplicationConfig` / `providedIn`
Feature providers	NgModules	Environment/route providers
Guards	Class-based	Functional guards
Resolvers	Class-based	Functional resolvers
Configuration	`InjectionToken`	`InjectionToken`
Provider factories	`useFactory`	`useFactory` + `inject()`
Library APIs	NgModule configuration	`provideX()` / `withX()`
Scope	Module/component	Environment/element/route/component

The important point is that Angular did not throw away DI.

Instead, Angular evolved the way DI is configured and consumed.

96. What You Should Learn for an Angular Interview

If an interviewer asks:

"Explain Dependency Injection in Angular."

Don't answer only:

"Angular injects services into components."

A strong answer is:

Angular's Dependency Injection system manages the creation and delivery of dependencies using tokens, providers, and injectors. A provider defines how a token should be resolved, while an injector performs the resolution and controls scope and lifetime. Modern Angular supports both constructor injection and the inject() function. Providers can be configured through providedIn, application/environment providers, routes, components, and directives. Angular also supports provider strategies such as useClass, useValue, useFactory, useExisting, and multi, while hierarchical injectors allow dependencies to be scoped and overridden at different levels.

Then explain:

Token
Provider
Injector
Scope
Resolution

That demonstrates real understanding.

97. The Mental Model You Should Remember

Whenever Angular sees:

inject(SomeDependency)

think:

What token is being requested?
          ↓
Which injector is currently active?
          ↓
Where is the nearest provider?
          ↓
What provider recipe is configured?
          ↓
Does Angular create or reuse an instance?
          ↓
What is the dependency's scope/lifetime?

For example:

inject(TaskRepository)

becomes:

TaskRepository
      ↓
Current Injector
      ↓
Find Provider
      ↓
useClass: HttpTaskRepository
      ↓
Create/Reuse HttpTaskRepository
      ↓
Resolve its dependencies
      ↓
Return instance

That is Angular DI.

98. The Complete Picture

Angular DI can be understood as five layers:

                    ┌──────────────────────┐
                    │       Consumer       │
                    │  Component/Service   │
                    └──────────┬───────────┘
                               │
                               │ inject(Token)
                               ↓
                    ┌──────────────────────┐
                    │       Injector       │
                    │   Resolve dependency │
                    └──────────┬───────────┘
                               │
                               ↓
                    ┌──────────────────────┐
                    │       Provider       │
                    │ useClass/useValue/   │
                    │ useFactory/useExisting│
                    └──────────┬───────────┘
                               │
                               ↓
                    ┌──────────────────────┐
                    │      Dependency      │
                    │ Service/Object/etc.  │
                    └──────────────────────┘

And the injector itself exists within a hierarchy:

                 EnvironmentInjector
                         │
             ┌───────────┴───────────┐
             │                       │
        Application              Feature/Route
             │                       │
             └───────────┬───────────┘
                         │
                  ElementInjector
                         │
                    Component
                         │
                   Child Component
                         │
                  Grandchild Component

99. Best Practices

1. Prefer `providedIn: 'root'` for true application-wide services

@Injectable({
  providedIn: 'root'
})

2. Use component providers for isolated state

@Component({
  providers: [
    FormState
  ]
})

3. Prefer `inject()` for modern Angular code

private service = inject(MyService);

4. Keep constructor injection when it makes sense

You don't need to rewrite every existing Angular application.

5. Use `InjectionToken` for interfaces and configuration

new InjectionToken<AppConfig>()

6. Use abstractions when implementations may change

abstract class PaymentGateway {}

7. Use `useExisting` when you need an alias to the same instance

8. Use `multi` for extensible collections

9. Don't make every service global

Scope dependencies intentionally.

10. Don't use `runInInjectionContext()` unnecessarily

Normal DI should remain the default.

11. Don't create duplicate `InjectionToken` instances

Export one token and reuse it.

12. Use Angular DevTools when debugging injector problems

Angular DevTools can visualize injector hierarchies, provider lists, and resolution paths, which is extremely useful when debugging complex DI behavior.

100. Final Cheat Sheet

// Root service
@Injectable({
  providedIn: 'root'
})
export class UserService {}

// Modern injection
private userService = inject(UserService);

// Classic injection
constructor(
  private userService: UserService
) {}

// Value
{
  provide: API_URL,
  useValue: 'https://api.example.com'
}

// Class
{
  provide: Logger,
  useClass: ConsoleLogger
}

// Alias
{
  provide: LegacyLogger,
  useExisting: Logger
}

// Factory
{
  provide: ApiClient,
  useFactory: () => {

    const http = inject(HttpClient);

    return new ApiClient(http);

  }
}

// Multiple providers
{
  provide: HANDLERS,
  useClass: ConsoleHandler,
  multi: true
}

// Optional
inject(Service, {
  optional: true
});

// Parent
inject(Service, {
  skipSelf: true
});

// Current injector only
inject(Service, {
  self: true
});

// Host boundary
inject(Service, {
  host: true
});

// InjectionToken
const CONFIG =
  new InjectionToken<AppConfig>(
    'CONFIG'
  );

// Component scope
@Component({
  providers: [
    LocalState
  ]
})

// Component view-only scope
@Component({
  viewProviders: [
    InternalService
  ]
})

// Modern application providers
bootstrapApplication(
  AppComponent,
  {
    providers: [
      provideRouter(routes),
      provideHttpClient()
    ]
  }
);

// Custom provider API
provideAnalytics({
  trackingId: '123'
});

Conclusion

Angular Dependency Injection is much more than:

constructor(private service: Service) {}

That syntax is only the visible surface.

Underneath it is a complete dependency-resolution system built around:

Tokens
   ↓
Providers
   ↓
Injectors
   ↓
Hierarchies
   ↓
Scopes
   ↓
Lifetimes
   ↓
Implementations

The evolution from:

constructor(...)

to:

inject(...)

didn't replace Angular DI.

It made DI usable in a much broader range of modern Angular APIs, including functional guards, resolvers, provider factories, standalone applications, environment providers, and library configuration.

The most important concepts to master are:

Dependency Injection
       ↓
Token
       ↓
Provider
       ↓
Injector
       ↓
EnvironmentInjector
       ↓
ElementInjector
       ↓
Hierarchical Resolution
       ↓
Provider Scope
       ↓
useClass
useValue
useFactory
useExisting
multi
       ↓
InjectionToken
       ↓
inject()
       ↓
Injection Context
       ↓
Self / SkipSelf / Host / Optional
       ↓
Standalone + provideX()
       ↓
Testing + Architecture

Once you understand these concepts, Angular DI stops being a collection of decorators and APIs.

You start seeing it as what it really is:

A runtime dependency-resolution and scoping system that allows Angular applications to separate what a component needs from how that dependency is created.

And that separation is one of the foundations of maintainable, testable, scalable Angular architecture.

References

Angular Dependency Injection Guide — Angular DI Documentation
Angular Hierarchical Injectors — Hierarchical Dependency Injection
Angular Provider Configuration — Defining Dependency Providers
Angular Injection Context — Injection Context
Angular inject() API — inject() API
Angular DevTools Injector Tree — Angular DevTools Injectors

DOM in Angular: Understanding the Document Object Model with Practical Examples

Abanoub Kerols — Sun, 06 Sep 2026 08:06:30 +0000

Angular applications are built around components, templates, data binding, directives, and a powerful rendering system.

But underneath all of that, your application still runs inside a browser, and the browser ultimately renders HTML elements through the DOM — Document Object Model.

Understanding how Angular interacts with the DOM is essential if you want to write efficient Angular applications, understand rendering behavior, work with browser APIs, and avoid common performance and security problems.

In this article, we will explore:

What the DOM is
How Angular interacts with the DOM
Angular's rendering model
ElementRef
Renderer2
ViewChild
ViewChildren
HostListener
HostBinding
DOCUMENT
Direct DOM manipulation
DOM events
Dynamic DOM changes
Angular lifecycle and the DOM
Change detection and DOM updates
SSR and hydration
Performance considerations
Security considerations
Real-world examples

1. What Is the DOM?

DOM stands for:

Document Object Model

When the browser receives HTML like:

<div>
  <h1>Hello Angular</h1>
  <button>Click Me</button>
</div>

The browser converts the HTML document into a tree-like structure.

Conceptually:

Document
└── html
    └── body
        └── div
            ├── h1
            │   └── "Hello Angular"
            └── button
                └── "Click Me"

Each HTML element becomes a DOM node.

JavaScript can interact with these nodes.

For example:

const button = document.querySelector('button');

button.textContent = 'Clicked';

The JavaScript code directly modifies the DOM.

2. The DOM in Angular

Angular adds another layer on top of the browser DOM.

Instead of manually manipulating HTML, Angular encourages you to describe what the UI should look like based on application state.

For example:

export class AppComponent {
  title = 'Hello Angular';
}

Template:

<h1>{{ title }}</h1>

Angular takes the component state:

title = "Hello Angular"

and renders:

<h1>Hello Angular</h1>

The browser then creates the corresponding DOM node.

Conceptually:

Component State
      ↓
Angular Template
      ↓
Angular Rendering Engine
      ↓
DOM
      ↓
Browser Screen

This is one of the most important concepts to understand.

3. Angular Does Not Mean "Never Touch the DOM"

You will often hear:

"Never manipulate the DOM directly in Angular."

This is an oversimplification.

The better rule is:

Avoid unnecessary direct DOM manipulation and prefer Angular abstractions when possible.

Angular provides APIs such as:

ElementRef
Renderer2
ViewChild
ViewChildren
HostListener
HostBinding
DOCUMENT

These allow Angular applications to interact with the DOM in a controlled way.

4. ElementRef

ElementRef provides access to the native DOM element associated with an Angular element.

Example:

import { Component, ElementRef, ViewChild } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <input #usernameInput placeholder="Enter username">
    <button (click)="focusInput()">Focus</button>
  `
})
export class ExampleComponent {

  @ViewChild('usernameInput')
  usernameInput!: ElementRef<HTMLInputElement>;

  focusInput() {
    this.usernameInput.nativeElement.focus();
  }
}

Here:

this.usernameInput.nativeElement

represents the actual browser element.

The DOM looks approximately like:

<input placeholder="Enter username">

5. Why ElementRef Can Be Dangerous

The problem is that nativeElement gives you direct access to the DOM.

For example:

this.usernameInput.nativeElement.style.color = 'red';

or:

this.usernameInput.nativeElement.innerHTML = userInput;

The second example can create security problems if the content is untrusted.

For example:

element.nativeElement.innerHTML = userInput;

If userInput contains malicious HTML, you may create an XSS vulnerability.

Therefore, avoid using ElementRef for general DOM manipulation when Angular provides a safer abstraction.

6. Renderer2

Angular provides Renderer2 for DOM manipulation.

Example:

import {
  Component,
  ElementRef,
  Renderer2
} from '@angular/core';

@Component({
  selector: 'app-box',
  template: `
    <div #box>Angular Box</div>
    <button (click)="changeColor()">Change Color</button>
  `
})
export class BoxComponent {

  constructor(
    private renderer: Renderer2,
    private elementRef: ElementRef
  ) {}

  changeColor() {
    const box = this.elementRef.nativeElement.querySelector('div');

    this.renderer.setStyle(
      box,
      'background-color',
      'blue'
    );
  }
}

Instead of:

box.style.backgroundColor = 'blue';

we use:

this.renderer.setStyle(
  box,
  'background-color',
  'blue'
);

7. Why Renderer2 Exists

Angular applications don't necessarily run only in a traditional browser DOM environment.

Angular can support environments such as:

Browser
Server-side rendering
Different rendering environments
Custom rendering implementations

Direct DOM APIs such as:

document.querySelector()

assume that a browser DOM exists.

Renderer2 gives Angular a more abstract mechanism for rendering operations.

Therefore:

Renderer2

is generally preferable to manually manipulating DOM APIs.

8. Renderer2 Common Operations

Set Attribute

this.renderer.setAttribute(
  element,
  'aria-label',
  'Close'
);

Remove Attribute

this.renderer.removeAttribute(
  element,
  'disabled'
);

Add Class

this.renderer.addClass(
  element,
  'active'
);

Remove Class

this.renderer.removeClass(
  element,
  'active'
);

Set Style

this.renderer.setStyle(
  element,
  'color',
  'red'
);

Remove Style

this.renderer.removeStyle(
  element,
  'color'
);

Create Element

const div = this.renderer.createElement('div');

Create Text

const text = this.renderer.createText(
  'Hello Angular'
);

Append Child

this.renderer.appendChild(
  parent,
  child
);

9. ViewChild

ViewChild is one of the most commonly used Angular APIs for accessing elements inside a component template.

Example:

<input #emailInput>

<button (click)="focusEmail()">
  Focus
</button>

Component:

@ViewChild('emailInput')
emailInput!: ElementRef<HTMLInputElement>;

focusEmail() {
  this.emailInput.nativeElement.focus();
}

The #emailInput syntax creates a template reference variable.

10. ViewChild With Components

ViewChild is not limited to DOM elements.

You can use it to access another Angular component.

Child:

@Component({
  selector: 'app-child',
  template: `
    <p>Child Component</p>
  `
})
export class ChildComponent {

  reset() {
    console.log('Child reset');
  }
}

Parent:

<app-child></app-child>
<button (click)="resetChild()">
  Reset
</button>

Parent component:

@ViewChild(ChildComponent)
child!: ChildComponent;

resetChild() {
  this.child.reset();
}

This is an important distinction:

@ViewChild('input')

can access an element.

While:

@ViewChild(ChildComponent)

can access a component instance.

11. AfterViewInit

If you need to access a DOM element through ViewChild, you need to understand Angular lifecycle timing.

Example:

import {
  AfterViewInit,
  Component,
  ElementRef,
  ViewChild
} from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <input #input>
  `
})
export class ExampleComponent
  implements AfterViewInit {

  @ViewChild('input')
  input!: ElementRef<HTMLInputElement>;

  ngAfterViewInit() {
    this.input.nativeElement.focus();
  }
}

Why?

Because Angular needs to create the component's view before the DOM element exists.

Lifecycle:

Constructor
     ↓
Angular creates component
     ↓
Template rendered
     ↓
View initialized
     ↓
ngAfterViewInit()

Therefore, DOM-related initialization often belongs in:

ngAfterViewInit()

12. ViewChildren

ViewChildren allows you to access multiple elements or components.

Example:

<input #input>
<input #input>
<input #input>

Component:

@ViewChildren('input')
inputs!: QueryList<ElementRef<HTMLInputElement>>;

You can iterate:

this.inputs.forEach(input => {
  console.log(input.nativeElement);
});

13. DOM Events in Angular

Normally, you don't need to manually attach DOM event listeners.

Angular provides event binding.

Example:

<button (click)="handleClick()">
  Click Me
</button>

Component:

handleClick() {
  console.log('Button clicked');
}

This is preferable to:

document
  .querySelector('button')
  ?.addEventListener('click', () => {});

Angular handles the event binding for you.

14. Event Object

You can also access the browser event.

<button (click)="handleClick($event)">
  Click
</button>

TypeScript:

handleClick(event: MouseEvent) {
  console.log(event);
}

For keyboard events:

<input (keydown)="handleKeyDown($event)">

handleKeyDown(event: KeyboardEvent) {
  console.log(event.key);
}

15. HostListener

HostListener allows a directive or component to listen to events.

Example:

import {
  Directive,
  HostListener
} from '@angular/core';

@Directive({
  selector: '[appHighlight]'
})
export class HighlightDirective {

  @HostListener('mouseenter')
  onMouseEnter() {
    console.log('Mouse entered');
  }

  @HostListener('mouseleave')
  onMouseLeave() {
    console.log('Mouse left');
  }
}

HTML:

<div appHighlight>
  Hover over me
</div>

Angular connects the events to the directive.

16. HostBinding

HostBinding allows you to bind a property, attribute, or class to the host element.

Example:

@HostBinding('class.active')
isActive = false;

Then:

toggle() {
  this.isActive = !this.isActive;
}

The host element automatically receives:

<div class="active">

when:

isActive === true

17. Renderer2 + HostListener Example

Let's create a reusable hover directive.

import {
  Directive,
  HostListener,
  Renderer2
} from '@angular/core';

@Directive({
  selector: '[appHover]'
})
export class HoverDirective {

  constructor(private renderer: Renderer2) {}

  @HostListener('mouseenter')
  onEnter() {
    this.renderer.setStyle(
      this.element,
      'transform',
      'scale(1.05)'
    );
  }

  @HostListener('mouseleave')
  onLeave() {
    this.renderer.removeStyle(
      this.element,
      'transform'
    );
  }

  private get element(): HTMLElement {
    return this.el.nativeElement;
  }

  constructor(
    private renderer: Renderer2,
    private el: ElementRef
  ) {}
}

The example demonstrates an important Angular pattern:

HostListener
      ↓
Event
      ↓
Renderer2
      ↓
DOM update

18. Angular Template Binding vs Direct DOM Manipulation

Consider this:

this.element.nativeElement.textContent = this.username;

Angular's preferred approach is:

<p>{{ username }}</p>

Why?

Because Angular can track application state and update the UI accordingly.

For example:

username = 'Abanoub';

changeName() {
  this.username = 'John';
}

Template:

<h2>{{ username }}</h2>

When the value changes, Angular updates the relevant DOM.

19. Property Binding

Angular provides property binding:

<button [disabled]="isLoading">
  Submit
</button>

Instead of:

button.disabled = isLoading;

Angular manages the relationship between state and DOM.

This is one of the fundamental ideas of Angular:

State
  ↓
Binding
  ↓
DOM

20. Attribute Binding

You can bind HTML attributes:

<button
  [attr.aria-label]="label">
  Save
</button>

You can also conditionally remove an attribute:

<div [attr.aria-hidden]="isHidden ? 'true' : null">
</div>

When the value is null, Angular removes the attribute.

21. Class Binding

Instead of manipulating:

element.classList.add('active');

you can use:

<div [class.active]="isActive">
</div>

Multiple classes can be controlled with:

<div
  [class.active]="isActive"
  [class.disabled]="isDisabled">
</div>

22. Style Binding

Example:

<div
  [style.color]="textColor"
  [style.font-size.px]="fontSize">
  Hello
</div>

Component:

textColor = 'red';
fontSize = 20;

Angular updates the DOM when these values change.

23. Structural Changes and the DOM

Angular can dynamically add and remove DOM nodes.

For example:

@if (isLoggedIn) {
  <p>Welcome back!</p>
}

When:

isLoggedIn = false;

the paragraph isn't rendered.

When:

isLoggedIn = true;

Angular creates the required DOM structure.

Conceptually:

isLoggedIn = false

DOM
└── No <p>


isLoggedIn = true

DOM
└── <p>Welcome back!</p>

24. @for and DOM Creation

Angular's modern control flow also provides:

@for (user of users; track user.id) {
  <div>
    {{ user.name }}
  </div>
}

Suppose:

users = [
  { id: 1, name: 'John' },
  { id: 2, name: 'Sarah' }
];

Angular creates DOM elements corresponding to these records.

The important part is:

track user.id

It gives Angular a stable identity for each item.

25. Why Tracking Matters

Imagine:

User 1
User 2
User 3
User 4

If you add:

User 5

Angular doesn't necessarily need to recreate every DOM element.

With stable tracking:

@for (user of users; track user.id)

Angular can efficiently identify which DOM nodes correspond to which data.

This becomes especially important with large lists.

26. Angular Change Detection and the DOM

Angular applications are usually driven by state changes.

For example:

count = 0;

increment() {
  this.count++;
}

Template:

<p>{{ count }}</p>

<button (click)="increment()">
  Increment
</button>

When the user clicks:

click
 ↓
increment()
 ↓
count++
 ↓
Angular detects changes
 ↓
Template binding evaluated
 ↓
DOM updated

Angular doesn't blindly rebuild the entire page.

It updates the parts of the rendered view that need to change.

27. Signals and DOM Updates

Modern Angular provides Signals.

Example:

import { signal } from '@angular/core';

count = signal(0);

increment() {
  this.count.update(value => value + 1);
}

Template:

<p>{{ count() }}</p>

<button (click)="increment()">
  Increment
</button>

The relationship becomes:

Signal
  ↓
Template dependency
  ↓
Angular knows what depends on the signal
  ↓
Relevant view update
  ↓
DOM

This makes Signals an important part of understanding modern Angular rendering.

28. Direct document Access

You can inject the browser Document using Angular's DOCUMENT token.

import {
  Component,
  Inject
} from '@angular/core';

import { DOCUMENT } from '@angular/common';

@Component({
  selector: 'app-example',
  template: `
    <button (click)="changeTitle()">
      Change Title
    </button>
  `
})
export class ExampleComponent {

  constructor(
    @Inject(DOCUMENT)
    private document: Document
  ) {}

  changeTitle() {
    this.document.title = 'Angular Application';
  }
}

This is useful for operations involving the document itself.

29. Why document.querySelector() Is Usually Not Recommended

You could write:

document.querySelector('#myElement');

But in Angular this is often the wrong abstraction.

Problems include:

1. Tight coupling

Your component becomes tightly coupled to a specific DOM structure.

2. Testing

Direct browser APIs can make testing more complicated.

3. SSR

The server doesn't have a normal browser DOM.

4. Maintainability

Angular template APIs are easier to reason about in many cases.

Prefer:

#myElement

and:

@ViewChild('myElement')

when you need access to an element in your component view.

30. Server-Side Rendering and the DOM

This becomes extremely important with Angular SSR.

In a normal browser:

document.querySelector(...)

works because a browser DOM exists.

On the server:

Node.js
   ↓
Angular SSR
   ↓
No normal browser DOM

Therefore, code like:

document.querySelector('button');

can fail during server rendering.

This is one reason Angular applications should avoid unnecessary direct browser APIs.

31. Browser-Only Code

If something genuinely requires browser APIs, Angular provides mechanisms to determine the execution environment.

For example:

import {
  Component,
  inject
} from '@angular/core';

import {
  isPlatformBrowser
} from '@angular/common';

import { PLATFORM_ID } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `...`
})
export class ExampleComponent {

  private platformId = inject(PLATFORM_ID);

  constructor() {
    if (isPlatformBrowser(this.platformId)) {
      // Browser-specific logic
    }
  }
}

This prevents browser-only logic from executing in a server environment.

32. DOM and Hydration

With SSR and hydration, Angular can first render HTML on the server.

Conceptually:

Server
  ↓
Angular SSR
  ↓
HTML
  ↓
Browser
  ↓
Existing DOM
  ↓
Hydration
  ↓
Interactive Angular Application

This means your Angular application needs to be careful about manually modifying the DOM before or during hydration.

Unexpected DOM changes can interfere with Angular's ability to match the server-rendered structure with the client-side application.

33. DOM Manipulation and Performance

DOM operations can be expensive.

For example, repeatedly doing:

element.style.width = ...
element.style.height = ...
element.style.left = ...
element.style.top = ...

inside a high-frequency event such as:

mousemove

can cause performance problems.

Better approaches include:

CSS classes
CSS animations
Angular bindings
Signals
requestAnimationFrame
minimizing DOM operations
avoiding unnecessary layout reads/writes

34. Layout Thrashing

A common browser performance problem is layout thrashing.

For example:

element.style.width = '500px';

const height = element.offsetHeight;

element.style.height = height + 'px';

Writing to the DOM and immediately reading layout information can force the browser to recalculate layout.

Repeated operations can become expensive.

Conceptually:

DOM Write
   ↓
Layout calculation
   ↓
DOM Read
   ↓
Layout calculation
   ↓
DOM Write
   ↓
...

Avoid unnecessary cycles like this.

35. Example: Better DOM Interaction

Instead of:

element.style.display = 'none';

Angular can often use:

@if (isVisible) {
  <div>
    Content
  </div>
}

Or class binding:

<div [class.hidden]="!isVisible">
  Content
</div>

This makes the UI declarative.

36. DOM vs Angular View

This distinction is important.

The DOM is the browser's representation of the document.

Angular's view is Angular's representation of the UI generated from:

Components
Templates
Directives
Bindings
Angular rendering instructions

Conceptually:

Angular Application
        │
        ├── Component
        │
        ├── Template
        │
        ├── Bindings
        │
        └── Directives
               │
               ↓
       Angular Rendering
               │
               ↓
             DOM
               │
               ↓
            Browser

Therefore, Angular developers should generally manipulate application state and templates, rather than treating the DOM as the primary source of truth.

37. Real-World Example: Auto Focus

Suppose you have:

<input #searchInput>

<button (click)="focusSearch()">
  Search
</button>

Component:

@ViewChild('searchInput')
searchInput!: ElementRef<HTMLInputElement>;

focusSearch() {
  this.searchInput.nativeElement.focus();
}

This is a legitimate use case for direct DOM access.

Why?

Because focusing an input is inherently a browser interaction.

38. Real-World Example: Dynamic CSS Class

Instead of:

this.renderer.addClass(element, 'selected');

Angular can often handle this declaratively:

<div [class.selected]="isSelected">
  Product
</div>

Component:

isSelected = false;

select() {
  this.isSelected = true;
}

This is usually simpler.

39. Real-World Example: Tooltip Directive

A directive can listen to mouse events:

@Directive({
  selector: '[appTooltip]'
})
export class TooltipDirective {

  @Input()
  appTooltip = '';

  @HostListener('mouseenter')
  showTooltip() {
    console.log(this.appTooltip);
  }

  @HostListener('mouseleave')
  hideTooltip() {
    console.log('Hide tooltip');
  }
}

HTML:

<button appTooltip="Delete this item">
  Delete
</button>

The directive interacts with the host element without requiring:

document.querySelector(...)

40. DOM Security

One of the most important rules when working with the DOM is:

Never blindly insert untrusted HTML into the DOM.

Avoid patterns such as:

element.innerHTML = userInput;

Especially when:

userInput

comes from:

User input
URL parameters
API responses
External content
Query strings

Angular provides security mechanisms and sanitization for many template scenarios.

Be especially careful with:

[innerHTML]="htmlContent"

and APIs such as:

DomSanitizer

Bypassing Angular's security mechanisms should only be done when you fully understand and trust the content.

41. innerHTML in Angular

Angular allows:

<div [innerHTML]="content"></div>

For example:

content = '<strong>Hello Angular</strong>';

Angular processes the value according to its security model.

However, don't assume that every value is safe just because you're using Angular.

Avoid blindly doing:

this.sanitizer.bypassSecurityTrustHtml(userInput);

This method does not magically make malicious content safe.

It tells Angular:

"I trust this value."

Therefore, the developer becomes responsible for that trust decision.

42. Common Mistakes

Mistake 1 — Excessive querySelector

Avoid:

document.querySelector(...)

for normal component interactions.

Prefer:

ViewChild

or template bindings.

Mistake 2 — Excessive ElementRef

Avoid using:

elementRef.nativeElement

for every UI operation.

Prefer:

[class.active]="isActive"

over:

element.classList.add('active');

Mistake 3 — Manipulating DOM Instead of State

Bad approach:

element.textContent = 'Loading...';

Better:

isLoading = true;

Template:

@if (isLoading) {
  <span>Loading...</span>
}

Mistake 4 — Ignoring SSR

This can be problematic:

window.localStorage.getItem('token');

when code may execute on the server.

Browser-only APIs should be handled appropriately in SSR applications.

43. When Should You Manipulate the DOM?

Direct DOM interaction is appropriate when the operation is inherently DOM-related.

Examples:

Focus

input.focus();

Measuring an element

element.getBoundingClientRect();

Integrating a third-party DOM library

For example:

Charting library
Rich text editor
Map library
Animation library

Low-level browser interaction

For example:

Selection API
Clipboard API
ResizeObserver
IntersectionObserver

However, use Angular abstractions where they make sense.

44. Angular DOM Best-Practice Hierarchy

A useful mental model is:

Level 1 — Template syntax

Prefer:

{{ value }}

[class.active]="isActive"

[disabled]="isLoading"

Level 2 — Angular APIs

Use:

ViewChild
ViewChildren
HostListener
HostBinding
Renderer2

when appropriate.

Level 3 — Native DOM APIs

Use:

nativeElement
document
window
querySelector

only when you genuinely need lower-level browser functionality.

The general idea:

Declarative Angular API
        ↓
Angular DOM abstraction
        ↓
Native DOM API

Use the highest level that solves the problem correctly.

45. Interview Question: What Is the DOM?

A strong answer:

The DOM, or Document Object Model, is the browser's object-based representation of an HTML document. It represents elements as a tree of nodes that JavaScript and other APIs can interact with. In Angular, templates and bindings are used to declaratively generate and update the DOM.

46. Interview Question: Should We Manipulate the DOM Directly in Angular?

A good answer:

Generally, Angular encourages declarative UI development through templates, bindings, directives, and component state. Direct DOM manipulation should be minimized because it can make applications harder to maintain, complicate SSR, and bypass Angular's rendering model. When DOM interaction is required, Angular APIs such as Renderer2, ViewChild, and HostListener can provide better integration.

47. Interview Question: ElementRef vs Renderer2

ElementRef

Provides access to the underlying native element:

elementRef.nativeElement

Useful for cases such as:

focus()

Renderer2

Provides an abstraction for DOM operations:

renderer.setStyle(...)
renderer.addClass(...)
renderer.setAttribute(...)

A simplified rule:

Need direct element interaction?
        ↓
ElementRef

Need DOM manipulation?
        ↓
Prefer Renderer2

48. Interview Question: Why Avoid document.querySelector()?

Because it:

couples code to DOM structure
bypasses Angular abstractions
can cause problems with SSR
makes components harder to test
can lead to maintainability problems

Instead, Angular provides:

ViewChild

ViewChildren

Renderer2

and template bindings.

49. Interview Question: When Is ngAfterViewInit Used?

ngAfterViewInit() runs after Angular has initialized the component's view.

It is useful when code needs access to view-related elements.

Example:

@ViewChild('input')
input!: ElementRef<HTMLInputElement>;

ngAfterViewInit() {
  this.input.nativeElement.focus();
}

The important concept is:

Component created
      ↓
Template rendered
      ↓
View initialized
      ↓
ngAfterViewInit

50. The Big Picture

If you want to understand DOM manipulation in Angular deeply, don't think about Angular as simply:

HTML + TypeScript

Instead, think:

Application State
       ↓
Angular Component
       ↓
Angular Template
       ↓
Bindings / Directives
       ↓
Angular Rendering System
       ↓
DOM
       ↓
Browser Rendering
       ↓
Pixels

When the state changes:

State Change
     ↓
Angular detects the relevant change
     ↓
View updates
     ↓
DOM changes
     ↓
Browser renders the result

This mental model is much more useful than thinking of Angular as a collection of DOM manipulation APIs.

Conclusion

The DOM is still the foundation of every Angular application's browser UI, but Angular gives developers a higher-level way to work with it.

The most important principles are:

Prefer Angular templates over manual DOM manipulation.
Use property, attribute, class, and style bindings whenever possible.
Use ViewChild when you need to access a specific element or component.
Use Renderer2 when you need programmatic DOM manipulation.
Use HostListener and HostBinding for reusable directive behavior.
Be careful with ElementRef.nativeElement.
Avoid unnecessary document.querySelector() usage.
Consider SSR and hydration when using browser APIs.
Avoid unsafe HTML manipulation and unnecessary sanitization bypasses.
Keep application state as the source of truth whenever possible.

The most important mindset is:

In Angular, don't ask "How do I manipulate this DOM element?" first. Ask "What state should my UI represent?"

Once you understand that distinction, Angular's rendering model, change detection, Signals, directives, lifecycle hooks, SSR, and DOM APIs become much easier to understand.

Building a Call Campaign Simulator with TypeScript

Abanoub Kerols — Wed, 02 Sep 2026 08:58:27 +0000

When building a system that manages automated phone campaigns, the problem is much more complicated than simply looping through a list of phone numbers and calling them.

A real campaign system needs to answer questions such as:

When is a customer allowed to be called?
How many calls can run simultaneously?
What happens when a call fails?
When should a failed call be retried?
How many minutes can we spend calling customers per day?
What happens when the campaign is paused?
How do we handle different timezones?
How can we test time-dependent behavior without waiting for real time?

This article explains how to design and implement a Call Campaign Simulator using TypeScript.

The goal is not only to implement the feature, but also to understand the software engineering concepts behind it.

1. What Is a Call Campaign Simulator?

A call campaign simulator receives a list of customers and attempts to call them according to a set of business rules.

For example:

Customers:
    555-0001
    555-0002
    555-0003
    555-0004

Working Hours:
    09:00 → 17:00

Maximum Concurrent Calls:
    3

Daily Call Limit:
    120 minutes

Maximum Retries:
    2

The system needs to coordinate all of these constraints.

Conceptually:

                 ┌────────────────────┐
                 │   Customer Queue   │
                 └─────────┬──────────┘
                           │
                           ▼
                 ┌────────────────────┐
                 │ Campaign Scheduler │
                 └─────────┬──────────┘
                           │
             ┌─────────────┼─────────────┐
             │             │             │
             ▼             ▼             ▼
          Call #1       Call #2       Call #3
             │             │             │
             └─────────────┼─────────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │ Call Result     │
                  └────────┬────────┘
                           │
                 ┌─────────┴─────────┐
                 │                   │
               Success              Failure
                 │                   │
                 ▼                   ▼
             Processed             Retry
                                     │
                                     ▼
                              Retry Scheduler

The important part is that the system is essentially a scheduler + state machine + concurrency controller.

2. Core Requirements

Our simulator supports the following features:

Sequential Processing

Customers are processed in the order they appear in the list.

[
  "555-0001",
  "555-0002",
  "555-0003"
]

The system should not randomly reorder customers.

Working Hours

Calls are only allowed during a configured time window.

Example:

09:00 → 17:00

If the current time is:

08:30

the campaign must wait.

If the current time is:

18:00

the campaign must also wait until the next valid working period.

Concurrency Control

Suppose:

maxConcurrentCalls = 3;

The system can have at most three active calls:

Call A → active
Call B → active
Call C → active

Call D → waiting
Call E → waiting

This is a classic concurrency limiting problem.

Daily Call Limit

Suppose:

maxDailyMinutes = 120;

The campaign cannot consume more than 120 minutes of call time during a calendar day.

For example:

Call 1 = 30 minutes
Call 2 = 40 minutes
Call 3 = 20 minutes
Call 4 = 30 minutes

Total:

30 + 40 + 20 + 30 = 120 minutes

The daily limit has been reached.

3. Why This Problem Is Interesting

At first glance, the implementation seems simple:

for (const customer of customers) {
    await call(customer);
}

But this ignores almost every important requirement.

We need to coordinate:

Time
   +
Concurrency
   +
Retries
   +
Daily Limits
   +
Pause / Resume
   +
Timezone
   +
State Management

This makes the problem a good example of asynchronous system design.

4. State Machine

One of the most important concepts in the project is the campaign state.

The campaign can have states such as:

type CampaignState =
  | "idle"
  | "running"
  | "paused"
  | "completed";

The state machine looks like:

             start()
                │
                ▼
             ┌───────┐
             │ idle  │
             └───┬───┘
                 │
                 ▼
             ┌─────────┐
       ┌────▶│ running │──────┐
       │     └────┬────┘      │
       │          │           │
    resume()   pause()     completed
       │          │           │
       │          ▼           ▼
       └──────┌────────┐   ┌───────────┐
              │ paused │   │ completed │
              └────────┘   └───────────┘

This is a Finite State Machine (FSM).

The important idea is that not every operation should be allowed from every state.

For example:

idle → start()       valid

running → pause()    valid

paused → resume()    valid

completed → resume() invalid

This prevents invalid transitions.

5. Data Model

The configuration can be represented using an interface.

export interface CampaignConfig {
  customerList: string[];

  startTime: string;
  endTime: string;

  maxConcurrentCalls: number;

  maxDailyMinutes: number;

  maxRetries?: number;

  retryDelayMs?: number;

  timezone?: string;
}

The configuration describes the rules of the campaign.

6. Call Handler

The campaign should not know how the actual call is performed.

Instead, we inject a function.

export type CallHandler = (
  phoneNumber: string
) => Promise<{
  answered: boolean;
  durationMs: number;
}>;

This is an important software design principle:

Separate business logic from infrastructure logic.

The Campaign class manages:

Scheduling
Concurrency
Retries
Limits
State

The CallHandler manages:

Actual call operation

This is similar to the Dependency Inversion Principle.

7. Why Dependency Injection Is Useful Here

Imagine we directly write:

class Campaign {
  async makeCall(phoneNumber: string) {
    // real telephony API
  }
}

Testing becomes difficult because every test would depend on the external telephony system.

Instead:

class Campaign {
  constructor(
    private callHandler: CallHandler
  ) {}
}

Now tests can inject:

const fakeCallHandler: CallHandler = async () => ({
  answered: true,
  durationMs: 5000
});

This gives us deterministic tests.

8. The Clock Abstraction

Time is another dependency.

A naive implementation might use:

Date.now();
setTimeout(...);
clearTimeout(...);

everywhere.

That makes testing time-dependent behavior difficult.

Instead, we define:

export interface IClock {
  now(): number;

  setTimeout(
    callback: () => void,
    delayMs: number
  ): number;

  clearTimeout(id: number): void;
}

The campaign now depends on an abstraction instead of directly depending on real system time.

9. Injected Clock

Production code can use the real clock:

const clock: IClock = {
  now: () => Date.now(),

  setTimeout: (callback, delayMs) =>
    setTimeout(callback, delayMs) as unknown as number,

  clearTimeout: (id) =>
    clearTimeout(id)
};

But tests can provide a fake clock.

For example:

class FakeClock implements IClock {
  private currentTime = 0;

  now(): number {
    return this.currentTime;
  }

  setTimeout(callback: () => void, delayMs: number): number {
    return 1;
  }

  clearTimeout(id: number): void {}
}

Now tests don't have to wait for real time.

10. Working Hours

Suppose:

startTime = "09:00";
endTime = "17:00";

We need to determine whether the current time is inside the allowed interval.

Conceptually:

function isWithinWorkingHours(
  currentTime: Date
): boolean {
  // convert current time to configured timezone

  // extract hours and minutes

  // compare against startTime and endTime
}

For example:

08:59 → false
09:00 → true
12:30 → true
16:59 → true
17:00 → false

Boundary conditions are important.

11. Waiting Until Working Hours

Suppose the campaign starts at:

07:30

and working hours are:

09:00 → 17:00

The campaign should not immediately call a customer.

Instead:

07:30
  │
  │ wait
  ▼
09:00
  │
  ▼
Start calling

The scheduler needs to calculate:

delay = nextWorkingStart - currentTime;

Then:

clock.setTimeout(
  () => processNext(),
  delay
);

12. Concurrency Control

Concurrency is one of the most important parts of the system.

Suppose:

maxConcurrentCalls = 2;

and we have:

Customer A
Customer B
Customer C
Customer D

The system should produce:

Time →

A ────────────────
B ──────────
C       ───────────────
D             ──────────

But never:

A ───────
B ───────
C ───────   ❌

because that would mean three simultaneous calls.

13. Concurrency Counter

A simple mechanism is:

private activeCalls = 0;

Before starting a call:

if (
  this.activeCalls >=
  this.config.maxConcurrentCalls
) {
  return;
}

When the call starts:

this.activeCalls++;

When it finishes:

this.activeCalls--;

This gives us a basic semaphore-like mechanism.

14. Semaphore Concept

A semaphore controls access to a limited resource.

If we have:

3 permits

then only three operations can execute simultaneously.

Initially:

Available permits = 3

Call A:

Available = 2

Call B:

Available = 1

Call C:

Available = 0

Call D:

WAIT

When A finishes:

Available = 1

D can now start.

This is exactly the type of resource management our campaign needs.

15. Daily Cap

Suppose:

maxDailyMinutes = 120;

We maintain:

private dailyMinutesUsed = 0;

When a call finishes:

const minutes =
  durationMs / 60000;

this.dailyMinutesUsed += minutes;

Before starting another call, we need to verify that the daily limit hasn't been reached.

16. Important Question: When Do We Count Call Minutes?

This is a business-rule decision.

Consider:

Remaining capacity = 5 minutes

and a call lasts:

10 minutes

There are several possible policies.

Policy A — Allow the call

Start the call and count the actual duration afterward.

Policy B — Reject the call

Don't start a call that could exceed the daily limit.

Policy C — Allow but cap accounting

Count only the remaining available minutes.

For a simulator, the cleanest approach is usually to clearly define the behavior in the requirements and implement it consistently.

This illustrates an important engineering principle:

Business rules should be explicit rather than hidden inside implementation details.

17. Daily Reset

The daily cap is not permanent.

For example:

Monday:
120 minutes used

Tuesday:
0 minutes used

So the system needs to know when a new calendar day begins.

This becomes more complicated when timezones are introduced.

18. Why Timezones Matter

Imagine:

timezone = "America/New_York";

The application server might actually be running in:

UTC

The campaign's business rules should still use:

New York time

For example:

Server:
14:00 UTC

New York:
10:00

If working hours are:

09:00 → 17:00

the call is allowed.

Therefore, we should never blindly use server-local time.

19. IANA Timezones

The project uses IANA timezone identifiers.

Examples:

America/New_York
Europe/London
Asia/Tokyo
Africa/Cairo

These identifiers allow the application to correctly interpret local time.

A library such as Luxon makes this easier.

Example:

import { DateTime } from "luxon";

const now = DateTime.now()
  .setZone("America/New_York");

console.log(now.toISO());

20. DST — Daylight Saving Time

Timezone handling becomes even more interesting with DST.

For example, some countries change their clocks during the year.

A hardcoded offset such as:

UTC-5

is therefore dangerous.

The correct approach is to use:

America/New_York

instead of manually calculating:

UTC - 5

The timezone database can determine the correct offset.

This is one reason timezone-aware libraries are useful.

21. Retry Logic

Calls can fail.

For example:

Customer A → success
Customer B → failed
Customer C → success

The system shouldn't necessarily permanently fail Customer B.

Instead:

Attempt 1
   │
   ▼
Failed
   │
   ▼
Wait
   │
   ▼
Attempt 2

If it fails again:

Attempt 2
   │
   ▼
Failed
   │
   ▼
Attempt 3

After the maximum retry count:

Permanently Failed

22. Retry Configuration

The configuration contains:

maxRetries: 2,
retryDelayMs: 3600000

This means the system can retry a failed call according to the configured retry policy.

The delay:

3600000 ms

equals:

1 hour

because:

1000 ms = 1 second

60 seconds = 1 minute

60 minutes = 1 hour

Therefore:

1000 × 60 × 60 = 3,600,000 ms

23. Retry Queue

Instead of immediately retrying:

await retry();

we can schedule it:

clock.setTimeout(
  () => retryCustomer(customer),
  retryDelayMs
);

The system can maintain:

private pendingRetries = 0;

When a retry is scheduled:

this.pendingRetries++;

When the retry starts:

this.pendingRetries--;

24. Exponential Backoff

A more advanced retry strategy is exponential backoff.

Instead of:

1 hour
1 hour
1 hour

we could use:

1 minute
2 minutes
4 minutes
8 minutes

The formula is:

delay =
  baseDelay * Math.pow(2, attempt);

For example:

attempt 0 → 1 minute
attempt 1 → 2 minutes
attempt 2 → 4 minutes
attempt 3 → 8 minutes

This is commonly used in distributed systems.

25. Pause and Resume

The campaign supports:

campaign.pause();

and:

campaign.resume();

The important business rule is:

Pausing the campaign does not necessarily cancel active calls.

For example:

Call A ────────────────► finishes
Call B ───────────► finishes

Campaign
         pause()
           │
           ▼
       PAUSED

Existing calls can finish while new calls should not be started.

26. Pause vs Cancellation

These concepts are different.

Pause

Stops starting new work.

Cancellation

Attempts to terminate existing work.

For example:

Pause:

Existing calls → continue
New calls      → blocked

Whereas cancellation could mean:

Existing calls → terminate if possible
New calls      → blocked

This distinction is important when designing asynchronous systems.

27. Campaign Status

The system exposes:

interface CampaignStatus {
  state:
    | "idle"
    | "running"
    | "paused"
    | "completed";

  totalProcessed: number;

  totalFailed: number;

  activeCalls: number;

  pendingRetries: number;

  dailyMinutesUsed: number;
}

This gives the outside world a snapshot of the campaign.

Example:

const status = campaign.getStatus();

console.log(status);

Possible output:

{
  state: "running",
  totalProcessed: 25,
  totalFailed: 2,
  activeCalls: 3,
  pendingRetries: 1,
  dailyMinutesUsed: 87.5
}

28. The Campaign Class

The central class can look conceptually like this:

export class Campaign {
  constructor(
    private config: CampaignConfig,
    private callHandler: CallHandler,
    private clock: IClock
  ) {}

  start(): void {
    // start campaign
  }

  pause(): void {
    // pause campaign
  }

  resume(): void {
    // resume campaign
  }

  getStatus(): CampaignStatus {
    // return campaign state
  }
}

This keeps the public API small.

29. Internal State

The campaign needs internal state such as:

private state: CampaignState = "idle";

private currentIndex = 0;

private activeCalls = 0;

private totalProcessed = 0;

private totalFailed = 0;

private pendingRetries = 0;

private dailyMinutesUsed = 0;

These variables represent the current state of the campaign.

30. Processing the Customer Queue

A basic processing function might look like:

private processNext(): void {
  if (this.state !== "running") {
    return;
  }

  if (
    this.activeCalls >=
    this.config.maxConcurrentCalls
  ) {
    return;
  }

  if (
    this.currentIndex >=
    this.config.customerList.length
  ) {
    this.checkCompletion();
    return;
  }

  const customer =
    this.config.customerList[
      this.currentIndex
    ];

  this.currentIndex++;

  this.executeCall(customer);
}

The important idea is that every condition acts as a gate.

31. The Scheduling Pipeline

Before starting a call, we conceptually check:

Is campaign running?
        │
        ▼
Are we inside working hours?
        │
        ▼
Is concurrency available?
        │
        ▼
Is daily capacity available?
        │
        ▼
Start call

This can be represented as:

                 ┌───────────────┐
                 │ Campaign      │
                 │ running?      │
                 └───────┬───────┘
                         │ yes
                         ▼
                 ┌───────────────┐
                 │ Working       │
                 │ hours?        │
                 └───────┬───────┘
                         │ yes
                         ▼
                 ┌───────────────┐
                 │ Concurrency   │
                 │ available?    │
                 └───────┬───────┘
                         │ yes
                         ▼
                 ┌───────────────┐
                 │ Daily cap     │
                 │ available?    │
                 └───────┬───────┘
                         │ yes
                         ▼
                    START CALL

This is effectively a scheduling decision tree.

32. Executing a Call

The call itself can be handled asynchronously:

private async executeCall(
  phoneNumber: string
): Promise<void> {
  this.activeCalls++;

  try {
    const result =
      await this.callHandler(phoneNumber);

    this.handleCallResult(
      phoneNumber,
      result
    );
  } finally {
    this.activeCalls--;
    this.processAvailableCalls();
  }
}

The finally block is particularly important.

Whether the call succeeds or fails:

this.activeCalls--;

must happen.

Otherwise the campaign could become permanently stuck.

33. Why `finally` Matters

Bad implementation:

try {
  await call();
  activeCalls--;
} catch {
  // activeCalls never decremented
}

If the call throws an exception:

activeCalls = 1

call throws

activeCalls stays 1

Eventually the system may believe that the concurrency limit has been reached forever.

Better:

try {
  await call();
} finally {
  activeCalls--;
}

This is a classic resource-cleanup pattern.

34. Handling Success

Suppose the call result is:

{
  answered: true,
  durationMs: 120000
}

We can calculate:

const minutes =
  durationMs / 60000;

Then:

this.dailyMinutesUsed += minutes;
this.totalProcessed++;

The customer is now considered successfully processed.

35. Handling Failure

Suppose:

{
  answered: false,
  durationMs: 5000
}

The business rule can decide that the call should be retried.

Conceptually:

if (attempt < maxRetries) {
  scheduleRetry();
} else {
  totalFailed++;
}

This creates two possible paths:

Failure
   │
   ├── retries remaining → Retry
   │
   └── no retries → Permanent failure

36. Attempt Tracking

Each customer needs retry information.

For example:

private retryAttempts =
  new Map<string, number>();

When a customer fails:

const attempts =
  this.retryAttempts.get(phoneNumber) ?? 0;

this.retryAttempts.set(
  phoneNumber,
  attempts + 1
);

This allows the system to know how many times a particular customer has already been attempted.

37. Important Design Question: Customer Identity

Using the phone number as a key is convenient:

Map<string, number>

But in a real system, phone numbers might not be unique or stable.

A production system would usually have:

customerId
phoneNumber

For example:

interface Customer {
  id: string;
  phoneNumber: string;
}

Then retry state can use:

Map<CustomerId, RetryState>

This is more robust.

38. Sequential Processing vs Concurrent Execution

The requirement says:

Process the customer list sequentially.

This does not necessarily mean:

await customer1;
await customer2;
await customer3;

because that would make concurrency impossible.

Instead, sequential processing usually means:

Customers are selected from the queue in order, while multiple selected calls may execute concurrently up to the configured limit.

For example:

Queue:

A
B
C
D
E

maxConcurrent = 2

A ──────────
B ─────────────

C       ─────────
D       ────────

E             ─────────

The selection order remains:

A → B → C → D → E

while execution overlaps.

This distinction is very important.

39. Completion Detection

The campaign should only become:

"completed"

when there is no more work.

That usually means:

Customer queue empty
+
Active calls = 0
+
Pending retries = 0

Therefore:

if (
  currentIndex >= customerList.length &&
  activeCalls === 0 &&
  pendingRetries === 0
) {
  state = "completed";
}

This avoids declaring completion too early.

40. Example Scenario

Consider:

const config: CampaignConfig = {
  customerList: [
    "555-0001",
    "555-0002",
    "555-0003",
    "555-0004"
  ],

  startTime: "09:00",

  endTime: "17:00",

  maxConcurrentCalls: 2,

  maxDailyMinutes: 60,

  maxRetries: 2,

  retryDelayMs: 60000,

  timezone: "America/New_York"
};

Suppose:

09:00

The campaign starts.

41. Initial Execution

Concurrency limit:

So:

Call 555-0001
Call 555-0002

are started.

The remaining customers wait:

555-0003
555-0004

42. First Call Finishes

Suppose:

555-0001
answered = true
duration = 10 minutes

Now:

dailyMinutesUsed = 10
activeCalls = 1

The scheduler can start:

555-0003

Now:

555-0002 → active
555-0003 → active

43. Failed Call

Suppose:

555-0002
answered = false

The system schedules a retry:

retry in 60 seconds

Status:

pendingRetries = 1

The campaign can continue processing other customers if capacity allows.

44. Retry

After the delay:

555-0002 → retry

If successful:

totalProcessed++

If it fails again:

attempt = 2

and the system checks whether another retry is allowed.

45. Daily Cap Reached

Suppose:

dailyMinutesUsed = 58

and a call finishes with:

duration = 5 minutes

Now:

dailyMinutesUsed = 63

The campaign has exceeded the configured limit if the system permits the call to finish.

At this point, the campaign should stop scheduling additional calls until the next applicable calendar day, according to the chosen business rule.

46. Why Luxon?

JavaScript's native Date API can become difficult to work with when implementing complex timezone behavior.

Luxon provides a cleaner API.

For example:

import { DateTime } from "luxon";

const now = DateTime.now()
  .setZone("Europe/London");

console.log(now.hour);
console.log(now.minute);

We can also calculate the start of the day:

const startOfDay =
  now.startOf("day");

And the next day:

const nextDay =
  now.plus({ days: 1 })
     .startOf("day");

This is useful for daily cap calculations.

47. Calendar Day vs 24 Hours

An important distinction:

Daily cap

usually means a calendar day, not:

rolling 24-hour window

For example:

Monday 23:50 → Tuesday 00:10

A calendar-day implementation treats these as different days.

A rolling-window implementation would treat them as part of the same 24-hour period.

The requirements explicitly describe:

maximum total call minutes per calendar day

Therefore the reset should happen at local midnight in the configured timezone.

48. Testing Time-Dependent Systems

One of the hardest things to test is code like:

setTimeout(() => {
  // retry after one hour
}, 3600000);

A normal test would have to wait one hour.

Obviously, that's unacceptable.

This is why dependency injection is so useful.

Instead of directly using:

Date.now()

we use:

clock.now()

Instead of:

setTimeout()

we use:

clock.setTimeout()

Now tests can control the clock.

49. Deterministic Testing

Suppose we want to test:

Retry after 1 hour

With a fake clock:

clock.advanceBy(60 * 60 * 1000);

We can simulate one hour instantly.

The test becomes:

Start
  ↓
Failure
  ↓
Schedule retry
  ↓
Advance clock 1 hour
  ↓
Retry executes

No real waiting is necessary.

This is an example of deterministic testing.

50. Testing Concurrency

We should test that:

activeCalls <= maxConcurrentCalls

at all times.

For:

maxConcurrentCalls = 3

we should never observe:

activeCalls = 4

A test can use a controlled call handler:

let active = 0;
let maximumObserved = 0;

const handler: CallHandler =
  async () => {
    active++;

    maximumObserved =
      Math.max(
        maximumObserved,
        active
      );

    // simulated work

    active--;

    return {
      answered: true,
      durationMs: 1000
    };
  };

Then assert:

expect(maximumObserved)
  .toBeLessThanOrEqual(3);

51. Testing Working Hours

Important test cases include:

08:59 → should not call
09:00 → should call
12:00 → should call
16:59 → should call
17:00 → should stop

Boundary conditions are often where scheduling bugs occur.

52. Testing Pause and Resume

Example:

Campaign starts
      ↓
Calls start
      ↓
pause()
      ↓
No new calls
      ↓
Active calls finish
      ↓
resume()
      ↓
New calls continue

The test should verify that pause does not accidentally create duplicate processing.

53. Testing Retries

A good retry test might simulate:

Attempt 1 → fail
Attempt 2 → fail
Attempt 3 → success

and verify:

totalProcessed === 1
totalFailed === 0

Another test:

Attempt 1 → fail
Attempt 2 → fail
Attempt 3 → fail

should produce:

totalProcessed === 0
totalFailed === 1

assuming the configured retry policy allows those attempts.

54. Testing Timezones

Timezone tests are particularly important.

For example:

Timezone:
America/New_York

Working hours:
09:00 → 17:00

The test should verify that UTC time is correctly converted into New York local time.

DST transition dates should also be tested.

This is one of the strongest reasons to abstract time and use a timezone-aware library.

55. A Complete Usage Example

The public API can remain simple:

import { Campaign } from "./solution";

import {
  IClock,
  CallHandler,
  CampaignConfig
} from "./interfaces";

const clock: IClock = {
  now: () => Date.now(),

  setTimeout: (callback, delayMs) =>
    setTimeout(
      callback,
      delayMs
    ) as unknown as number,

  clearTimeout: (id) =>
    clearTimeout(id)
};

const callHandler: CallHandler =
  async (phoneNumber) => {

    console.log(
      `Calling ${phoneNumber}`
    );

    return {
      answered:
        Math.random() > 0.2,

      durationMs:
        Math.random() * 600000
    };
  };

const config: CampaignConfig = {
  customerList: [
    "555-0001",
    "555-0002",
    "555-0003",
    "555-0004"
  ],

  startTime: "09:00",

  endTime: "17:00",

  maxConcurrentCalls: 3,

  maxDailyMinutes: 120,

  maxRetries: 2,

  retryDelayMs: 3600000,

  timezone: "America/New_York"
};

const campaign =
  new Campaign(
    config,
    callHandler,
    clock
  );

campaign.start();

Then we can inspect the status:

setInterval(() => {
  const status =
    campaign.getStatus();

  console.log({
    state: status.state,

    processed:
      status.totalProcessed,

    failed:
      status.totalFailed,

    activeCalls:
      status.activeCalls,

    pendingRetries:
      status.pendingRetries,

    dailyMinutes:
      status.dailyMinutesUsed
  });
}, 1000);

56. Architectural View

The project can be viewed as several logical components:

                    Campaign
                       │
       ┌───────────────┼────────────────┐
       │               │                │
       ▼               ▼                ▼
  Scheduler        Call Handler      State
       │               │                │
       ▼               ▼                ▼
 Working Hours      External API     Metrics
 Concurrency
 Daily Cap
 Retries
 Timezone

The Campaign orchestrates the system.

57. Separation of Concerns

A good implementation should avoid putting everything into one giant function.

Instead, separate responsibilities.

For example:

isWithinWorkingHours()

handles working hours.

getNextWorkingTime()

handles scheduling.

executeCall()

handles call execution.

scheduleRetry()

handles retries.

checkDailyLimit()

handles daily capacity.

checkCompletion()

handles completion.

This makes the code easier to understand and test.

58. Common Mistakes

Mistake 1 — Using `Promise.all()`

A naive implementation:

await Promise.all(
  customers.map(call)
);

can create hundreds or thousands of simultaneous calls.

That violates:

maxConcurrentCalls

Mistake 2 — Using Recursive Calls Without Guards

Something like:

processNext();

inside multiple asynchronous paths can accidentally create duplicate processing.

A scheduler should carefully control when the next task can start.

Mistake 3 — Forgetting `finally`

As discussed earlier:

activeCalls++;

must eventually be paired with:

activeCalls--;

even when an exception occurs.

Mistake 4 — Using Server Time for Business Rules

This is dangerous:

new Date();

without considering the configured campaign timezone.

Business time should be calculated using:

configured timezone

Mistake 5 — Treating Retry as a New Customer

A retry should not incorrectly increment:

totalProcessed

until the customer actually succeeds.

Retry attempts and successfully processed customers are different metrics.

59. Metrics vs Events

Another useful distinction is between:

Attempts

and:

Processed Customers

Suppose:

Customer A:
Attempt 1 → failed
Attempt 2 → failed
Attempt 3 → success

The system made:

3 attempts

but successfully processed:

1 customer

These should not be confused.

A production system might expose:

totalAttempts
totalProcessed
totalFailed

instead of only two counters.

60. What Happens if the Process Crashes?

The current simulator is primarily an in-memory system.

That means state such as:

currentIndex
activeCalls
dailyMinutesUsed
retryAttempts

can disappear if the Node.js process crashes.

A production campaign platform would need persistent state.

For example:

Campaign Service
       │
       ▼
   PostgreSQL
       │
       ├── campaigns
       ├── customers
       ├── call_attempts
       └── retry_jobs

Or possibly:

Redis

for short-lived scheduling state.

61. Production Architecture

A more advanced architecture could look like:

                    API
                     │
                     ▼
             Campaign Service
                     │
          ┌──────────┴──────────┐
          │                     │
          ▼                     ▼
      Database                Queue
                                │
                  ┌─────────────┼─────────────┐
                  │             │             │
                  ▼             ▼             ▼
               Worker        Worker        Worker
                  │             │             │
                  └─────────────┼─────────────┘
                                │
                                ▼
                         Telephony Provider

The simulator's concurrency limit becomes a distributed worker problem.

62. Queue-Based Architecture

For a real system, instead of keeping all work inside one process, we could use a message queue.

For example:

Campaign
   │
   ▼
Queue
   │
   ├── Job 1
   ├── Job 2
   ├── Job 3
   └── Job 4

Workers consume jobs.

Concurrency can then be controlled by:

Number of workers
+
Per-worker concurrency

This architecture scales much better.

63. Idempotency

Distributed systems introduce another important problem:

What happens if the same call job is processed twice?

For example:

Worker A:
starts call

Network failure

Queue thinks job failed

Worker B:
starts same job

Now the customer might receive two calls.

A production system therefore needs an idempotency strategy.

For example:

idempotencyKey =
  `${campaignId}:${customerId}:${attempt}`;

Before starting the call, the system can check whether that attempt was already executed.

64. Race Conditions

Concurrency introduces race conditions.

Consider:

Daily limit remaining:
5 minutes

Two workers check simultaneously:

Worker A → sees 5 minutes
Worker B → sees 5 minutes

Both decide:

Allowed

Then both consume:

5 minutes

Now the system has exceeded its intended capacity.

This is a classic check-then-act race condition.

A production system would need synchronization, transactions, atomic operations, or another coordination mechanism.

65. Why the Simulator Is Valuable

Although this project is called a simulator, it demonstrates several real backend concepts:

Async Programming
Concurrency
Scheduling
State Machines
Dependency Injection
Retry Strategies
Resource Limits
Timezones
Testing
Race Conditions
Queue Processing
Fault Tolerance

These are not merely theoretical concepts.

They appear in:

Job schedulers
Email systems
Payment processing
Notification services
Data pipelines
Background workers
Distributed systems
Call centers
IoT platforms

66. Complexity

Suppose there are:

N customers

Each customer is processed a finite number of times based on retry configuration.

If:

R = maximum retries

the maximum number of attempts is approximately:

N × (R + 1)

For example:

100 customers
2 retries

Maximum attempts:

100 × 3 = 300

The scheduler therefore needs to handle potentially much more work than the number of customers.

67. Memory Complexity

If we maintain retry state for each customer:

Map<CustomerId, RetryState>

the memory requirement is approximately:

O(N)

where N is the number of customers.

Other queues and state structures may also contribute to memory usage.

68. Concurrency Complexity

The system limits active calls to:

where:

C = maxConcurrentCalls

Therefore the number of simultaneously active operations is bounded by:

O(C)

rather than:

O(N)

This is one of the primary purposes of the concurrency control mechanism.

69. Key Design Principles

This project demonstrates several important principles.

Single Responsibility

Each part of the system should have one main responsibility.

Dependency Inversion

Depend on:

IClock
CallHandler

rather than concrete implementations.

Separation of Concerns

Scheduling logic should not be mixed with call-provider implementation.

Explicit State

Campaign state should be represented explicitly.

Deterministic Testing

Inject time and external dependencies.

Defensive Resource Management

Always release resources using patterns such as:

finally

70. Complete Mental Model

The easiest way to understand the entire system is:

                CUSTOMER LIST
                      │
                      ▼
                QUEUE / INDEX
                      │
                      ▼
              ┌───────────────┐
              │   Scheduler   │
              └───────┬───────┘
                      │
          ┌───────────┼───────────┐
          │           │           │
          ▼           ▼           ▼
       Time        Capacity     State
          │           │           │
          └───────────┼───────────┘
                      │
                      ▼
                 CALL HANDLER
                      │
             ┌────────┴────────┐
             │                 │
          Success            Failure
             │                 │
             ▼                 ▼
        Update stats        Retry?
             │                 │
             │          ┌──────┴──────┐
             │          │             │
             │         Yes            No
             │          │             │
             │          ▼             ▼
             │       Schedule       Failed
             │        retry
             │          │
             └──────────┴─────────────┐
                                      │
                                      ▼
                              Check Completion
                                      │
                                      ▼
                                  COMPLETED

71. Final Takeaways

Building a call campaign simulator is a great exercise because it looks simple but contains many real-world backend problems.

The main lessons are:

1. Concurrency must be controlled

Don't start unlimited asynchronous operations.

maxConcurrentCalls

defines the resource boundary.

2. Time should be abstracted

Instead of tightly coupling the application to:

Date.now()
setTimeout()

inject a clock.

3. Timezones are business logic

Working hours and daily limits should be evaluated in the campaign's configured timezone.

4. Retries need explicit policies

A retry system should define:

maximum attempts
delay
backoff strategy
permanent failure behavior

5. State machines simplify lifecycle management

Explicit states such as:

idle
running
paused
completed

make the campaign's behavior predictable.

6. Testing asynchronous systems requires control

Injected clocks and fake call handlers allow tests to run quickly and deterministically.

7. In-memory solutions are different from production systems

A simulator can keep state in memory.

A production system usually needs:

Database
Queue
Workers
Idempotency
Transactions
Distributed locking
Monitoring

Conclusion

The Call Campaign Simulator is more than a TypeScript exercise.

It is a compact example of how backend systems coordinate:

Time
+
Concurrency
+
Retries
+
Resource Limits
+
State
+
External Dependencies

The most important lesson is that asynchronous programming is not only about using async and await.

Real asynchronous systems require coordination.

You need to answer:

Who is allowed to execute?

When are they allowed to execute?

How many can execute simultaneously?

What happens when execution fails?

What happens when time changes?

What happens when the process pauses?

How do we know the system has actually completed?

Once you start thinking about these questions, the problem moves from simply writing code to designing a reliable system.

And that's exactly why this type of task is valuable for understanding backend engineering and distributed-system concepts.

Source Code

Interested in exploring the implementation?

👉 View the complete Call Campaign Simulator on GitHub

The repository contains the complete TypeScript implementation, including concurrency control, retry logic, scheduling, daily limits, timezone support, and an injected clock for testability.

Delivery Slot Allocation: Designing a Safe and Concurrent Booking System

Abanoub Kerols — Mon, 31 Aug 2026 07:33:45 +0000

When building an e-commerce, food delivery, logistics, or appointment-booking system, one common problem appears again and again:

How can we allocate a limited resource to multiple customers without overbooking it?

A delivery slot is a perfect example of a shared resource.

Imagine that a delivery slot can handle only 5 orders:

10:00 - 12:00
Capacity: 5
Booked: 4

There is only one remaining position.

If two customers try to book the slot at exactly the same time, our backend must guarantee that only one of them gets the final position.

This article explains how to design such a system using:

Capacity management
Availability checking
Atomic database operations
Race-condition prevention
Alternative slot selection
Transactions and rollback
Concurrent request handling
Idempotency
Error handling

1. Understanding the Problem

Let's start with the delivery slot model.

A slot contains:

Slot
├── id
├── startTime
├── endTime
├── capacity
└── bookedCount

For example:

Slot ID: SLOT_01
Start: 10:00
End: 12:00
Capacity: 5
Booked Count: 3

The fundamental availability rule is:

bookedCount < capacity

Therefore:

3 < 5 → Available

But:

5 < 5 → False

So the slot is fully booked.

2. The Booking Request

A customer might send:

{
  "customerId": "C001",
  "orderId": "O001",
  "preferredSlotId": "SLOT_01"
}

The backend needs to:

Validate the request.
Find the requested slot.
Check availability.
Reserve capacity.
Create the reservation.
Return a confirmation.

The basic flow is:

Client
   |
   v
Validate Request
   |
   v
Find Slot
   |
   v
Check Availability
   |
   v
Reserve Capacity
   |
   v
Create Reservation
   |
   v
Return Confirmation

3. Why a Simple Availability Check Is Not Enough

A naive implementation might look like this:

const slot = await Slot.findById(slotId);

if (slot.bookedCount >= slot.capacity) {
    throw new Error("Slot is full");
}

slot.bookedCount += 1;

await slot.save();

At first glance, this looks correct.

But there is a serious concurrency problem.

4. The Race Condition Problem

Suppose we have:

Capacity = 5
Booked = 4

There is only one available position.

Now two requests arrive almost simultaneously:

Customer A
Customer B

The operations could happen like this:

Customer A → READ → bookedCount = 4
Customer B → READ → bookedCount = 4

Customer A → available
Customer B → available

Customer A → bookedCount = 5
Customer B → bookedCount = 6

Now we have:

Capacity = 5
Booked = 6

This is overbooking.

The problem isn't the availability condition itself.

The problem is that:

CHECK

and

UPDATE

are separate operations.

Between the check and the update, another request can modify the data.

This is called a:

Race Condition

5. What Is a Race Condition?

A race condition occurs when the result of an operation depends on the timing or ordering of concurrent operations.

In our case:

Request A
   |
   | Check availability
   |
   |--------+
            |
Request B   |
   |        |
   | Check  |
   |        |
   | Update |
   |        |
   |--------+
   |
   | Update

Both requests saw the same state.

That's why simply checking:

if (bookedCount < capacity)

is not enough.

We need to make the critical operation atomic.

6. Atomic Operations

An atomic operation is an operation that happens as one indivisible unit.

For our problem, we want the database to perform:

Check:

bookedCount < capacity

AND

Increment:

bookedCount = bookedCount + 1

as one operation.

Conceptually:

UPDATE delivery_slots
SET booked_count = booked_count + 1
WHERE id = ?
AND booked_count < capacity;

The important part is:

WHERE booked_count < capacity

The database itself decides whether capacity is still available.

7. Why Atomic Updates Solve the Problem

Consider:

Capacity = 5
Booked = 4

Two customers attempt to reserve the last position.

Request A executes:

UPDATE delivery_slots
SET booked_count = booked_count + 1
WHERE id = 'SLOT_01'
AND booked_count < capacity;

The condition is true.

The database updates:

Booked = 5

Now Request B executes the same operation.

The condition becomes:

5 < 5

which is false.

Therefore:

Rows affected = 0

Request B knows that the slot is no longer available.

The final state remains:

Capacity = 5
Booked = 5

No overbooking occurs.

8. A Generic Reservation Algorithm

The core algorithm can be represented as:

FUNCTION reserveSlot(slotId):

    UPDATE slot
    WHERE id = slotId
    AND bookedCount < capacity

    SET bookedCount = bookedCount + 1

    IF no row was updated:
        RETURN "Slot unavailable"

    RETURN "Slot reserved"

The database becomes responsible for enforcing the capacity condition.

9. Implementing It With Node.js

Let's assume we are using Node.js with a SQL database.

A repository method could look like:

async function reserveSlot(slotId) {
    const result = await db.query(
        `
        UPDATE delivery_slots
        SET booked_count = booked_count + 1
        WHERE id = ?
        AND booked_count < capacity
        `,
        [slotId]
    );

    return result.affectedRows === 1;
}

Now:

const reserved = await reserveSlot(slotId);

if (!reserved) {
    return {
        success: false,
        message: "Slot is no longer available"
    };
}

This is much safer than:

SELECT → check → UPDATE

10. The Complete Booking Service

A service layer can coordinate the entire process.

async function bookDeliverySlot({
    customerId,
    orderId,
    preferredSlotId
}) {

    if (!customerId) {
        throw new Error("Customer ID is required");
    }

    if (!orderId) {
        throw new Error("Order ID is required");
    }

    if (!preferredSlotId) {
        throw new Error("Preferred slot ID is required");
    }

    const slot = await findSlotById(preferredSlotId);

    if (!slot) {
        throw new Error("Delivery slot not found");
    }

    const reserved = await reserveSlot(preferredSlotId);

    if (!reserved) {

        const alternatives =
            await findAvailableAlternativeSlots(
                preferredSlotId
            );

        return {
            success: false,
            message: "The selected delivery slot is unavailable",
            alternatives
        };
    }

    const reservation = await createReservation({
        customerId,
        orderId,
        slotId: preferredSlotId
    });

    return {
        success: true,
        message: "Delivery slot booked successfully",
        reservation
    };
}

However, there is another important problem.

11. What Happens If Reservation Creation Fails?

Imagine this sequence:

1. Increment bookedCount
2. Create reservation

The database state becomes:

bookedCount = 5

But then:

createReservation()

fails.

Now the system says:

Booked = 5

even though the customer doesn't actually have a reservation.

We have consumed capacity without creating the booking.

This creates an inconsistent state.

12. Transactions

This is where a database transaction becomes useful.

We want:

Reserve slot
      +
Create reservation

to behave as one logical operation.

Either:

Both succeed

or:

Both fail

Conceptually:

BEGIN TRANSACTION

    Reserve slot

    Create reservation

COMMIT

If something fails:

BEGIN TRANSACTION

    Reserve slot

    Create reservation ❌

ROLLBACK

The rollback restores the previous state.

13. Transaction-Based Implementation

A simplified SQL-style implementation:

async function bookDeliverySlot({
    customerId,
    orderId,
    preferredSlotId
}) {

    const transaction = await db.beginTransaction();

    try {

        const slot = await findSlotById(
            preferredSlotId,
            transaction
        );

        if (!slot) {
            throw new Error("Delivery slot not found");
        }

        const result = await transaction.query(
            `
            UPDATE delivery_slots
            SET booked_count = booked_count + 1
            WHERE id = ?
            AND booked_count < capacity
            `,
            [preferredSlotId]
        );

        if (result.affectedRows === 0) {

            await transaction.rollback();

            const alternatives =
                await findAvailableAlternativeSlots(
                    preferredSlotId
                );

            return {
                success: false,
                message: "The selected delivery slot is unavailable",
                alternatives
            };
        }

        const reservation =
            await createReservation(
                {
                    customerId,
                    orderId,
                    slotId: preferredSlotId
                },
                transaction
            );

        await transaction.commit();

        return {
            success: true,
            message: "Delivery slot booked successfully",
            reservation
        };

    } catch (error) {

        await transaction.rollback();

        throw error;
    }
}

The exact transaction API depends on the database driver or ORM.

14. Finding Alternative Slots

A good booking system shouldn't simply tell the customer:

Slot unavailable.

It can improve the user experience by suggesting alternatives.

For example:

Requested:
12:00 - 14:00

Alternatives:

10:00 - 12:00
14:00 - 16:00
16:00 - 18:00

The query could be conceptually:

SELECT *
FROM delivery_slots
WHERE id != ?
AND booked_count < capacity
AND start_time > CURRENT_TIMESTAMP
ORDER BY start_time;

15. Ranking Alternative Slots

Not every available slot is equally useful.

We could rank alternatives according to:

Option 1 — Closest time

Requested: 12:00

10:00
14:00
16:00
18:00

Option 2 — Earliest available

Option 3 — Business priority

For example:

Same day
↓
Nearest time
↓
Lowest delivery cost

The business rules determine the sorting strategy.

16. Alternative Slot Function

A simple implementation:

async function findAvailableAlternativeSlots(
    preferredSlotId
) {

    const preferredSlot =
        await findSlotById(preferredSlotId);

    if (!preferredSlot) {
        return [];
    }

    return await Slot.find({
        _id: {
            $ne: preferredSlotId
        },
        bookedCount: {
            $lt: "$capacity"
        },
        startTime: {
            $gt: new Date()
        }
    }).sort({
        startTime: 1
    });
}

The exact syntax depends on the database.

For SQL databases, the equivalent condition would typically be:

booked_count < capacity

17. MongoDB Version

If the backend uses MongoDB, the same principle can be implemented with a conditional atomic update.

For example:

const slot = await DeliverySlot.findOneAndUpdate(
    {
        _id: slotId,
        $expr: {
            $lt: ["$bookedCount", "$capacity"]
        }
    },
    {
        $inc: {
            bookedCount: 1
        }
    },
    {
        new: true
    }
);

The important part is:

$expr: {
    $lt: ["$bookedCount", "$capacity"]
}

combined with:

$inc: {
    bookedCount: 1
}

The operation is performed atomically for the document.

If the result is:

null

the slot could not be reserved.

18. Handling Concurrent Requests With MongoDB

Suppose:

Capacity = 5
Booked = 4

Two requests execute:

findOneAndUpdate(...)

Request A succeeds:

Booked = 5

Request B evaluates:

5 < 5

which is false.

Therefore:

slot === null

Request B can then search for alternatives.

This protects the shared resource from overbooking.

19. The Complete Flow

The complete system can be represented as:

                    Customer
                       |
                       v
                Booking Request
                       |
                       v
                Validate Input
                       |
             +---------+---------+
             |                   |
          Invalid              Valid
             |                   |
             v                   v
        Return Error       Find Requested Slot
                                 |
                         +-------+-------+
                         |               |
                      Not Found        Found
                         |               |
                         v               v
                   Return Error    Attempt Atomic
                                    Reservation
                                         |
                              +----------+----------+
                              |                     |
                           Success                Failed
                              |                     |
                              v                     v
                       Create Booking       Find Alternatives
                              |                     |
                              v              +------+------+
                           Commit            |             |
                              |           Found          None
                              v             |             |
                          Success           v             v
                                     Return Options   Return Error

20. API Design

A REST API might expose:

POST /api/delivery-slots/book

Request:

{
  "customerId": "C001",
  "orderId": "O001",
  "preferredSlotId": "SLOT_01"
}

Successful response:

{
  "success": true,
  "message": "Delivery slot booked successfully",
  "reservation": {
    "id": "RES_001",
    "slotId": "SLOT_01",
    "customerId": "C001",
    "orderId": "O001"
  }
}

If the slot becomes unavailable:

{
  "success": false,
  "message": "The selected delivery slot is unavailable",
  "alternatives": [
    {
      "id": "SLOT_02",
      "startTime": "14:00",
      "endTime": "16:00"
    },
    {
      "id": "SLOT_03",
      "startTime": "16:00",
      "endTime": "18:00"
    }
  ]
}

21. HTTP Status Codes

The API can also use appropriate HTTP status codes.

For successful booking:

201 Created

Invalid request:

400 Bad Request

Unknown slot:

404 Not Found

Slot unavailable:

409 Conflict

Server/database failure:

500 Internal Server Error

Using:

409 Conflict

for an unavailable shared resource is particularly useful because the request itself can be valid while the resource state has changed.

22. Idempotency

There is another important issue.

Imagine the customer clicks:

Book

and the request succeeds.

But the network is slow.

The frontend doesn't receive the response.

The customer clicks again.

Now the backend receives:

Request 1
Request 2

Both may attempt to reserve capacity.

This can create duplicate reservations.

A common solution is an idempotency key.

For example:

Idempotency-Key: 8d7f9c21

The backend stores the result associated with that key.

If the same request arrives again:

Same Idempotency Key
        |
        v
Existing result?
        |
       Yes
        |
        v
Return previous result

Instead of creating another reservation.

23. Database Constraints

Application logic should not be the only protection.

The database should also enforce important invariants where possible.

For example, we want:

bookedCount <= capacity

The exact constraint strategy depends on the database.

This leads to an important backend principle:

Business-critical invariants should be protected as close to the data as practical.

The application controls the workflow, while the database protects data integrity.

24. Why "Read Then Write" Is Dangerous

This pattern is common:

const slot = await getSlot();

if (slot.bookedCount < slot.capacity) {

    slot.bookedCount++;

    await updateSlot(slot);
}

It looks reasonable, but under concurrency it becomes:

READ
  ↓
CHECK
  ↓
WAIT
  ↓
WRITE

Another request can modify the resource during that window.

A safer pattern is:

CONDITIONAL UPDATE

For example:

UPDATE delivery_slots
SET booked_count = booked_count + 1
WHERE id = ?
AND booked_count < capacity;

This moves the critical decision into the database operation itself.

25. Edge Cases

A production-ready implementation should consider more than the happy path.

Missing customer

Customer ID is required

Missing order

Order ID is required

Missing slot

Preferred slot ID is required

Unknown slot

Delivery slot not found

Full slot

Find alternatives

No alternatives

No available delivery slots

Concurrent booking

Use atomic reservation

Reservation creation failure

Rollback transaction

Duplicate booking

Use idempotency / unique constraints

Slot in the past

The system should reject expired slots:

startTime <= currentTime

Cancelled reservation

If a customer cancels:

bookedCount = bookedCount - 1

This operation should also be performed safely.

26. Cancellation

Booking isn't the only operation that affects capacity.

Suppose:

Capacity = 5
Booked = 5

A customer cancels.

We need:

Booked = 4

A safe operation could be:

UPDATE delivery_slots
SET booked_count = booked_count - 1
WHERE id = ?
AND booked_count > 0;

Again, the condition protects the invariant:

bookedCount >= 0

27. Testing Concurrent Booking

Concurrency should not only be discussed theoretically.

It should also be tested.

Suppose:

Capacity = 100
Booked = 99

Send:

10 concurrent requests

Expected result:

1 successful reservation
9 rejected requests

The final state must be:

Capacity = 100
Booked = 100

Never:

Booked = 101

A conceptual test:

const requests = Array.from(
    { length: 10 },
    (_, index) =>
        bookDeliverySlot({
            customerId: `C${index}`,
            orderId: `O${index}`,
            preferredSlotId: "SLOT_01"
        })
);

const results = await Promise.allSettled(requests);

const successfulBookings =
    results.filter(
        result =>
            result.status === "fulfilled" &&
            result.value.success
    );

console.log(
    successfulBookings.length
);

For a slot with one remaining position, the expected successful booking count is:

28. Important Architecture Principle

This problem demonstrates an important backend concept:

A delivery slot is not just a database record. It is a shared, limited resource.

Whenever multiple requests can consume the same limited resource, we need to think about:

Concurrency
+
Consistency
+
Atomicity
+
Data Integrity

The same concepts appear in:

Inventory systems
Seat booking
Hotel rooms
Appointment scheduling
Warehouse capacity
Payment processing
Ticket booking
Restaurant reservations
Rate-limit counters

The resource changes, but the concurrency problem remains similar.

29. A Better Production Architecture

A production system might separate responsibilities into layers:

Controller
    |
    v
Booking Service
    |
    v
Slot Repository
    |
    v
Database

Controller

Responsible for:

HTTP request
HTTP response
Input extraction

Service

Responsible for:

Business rules
Booking workflow
Alternative selection
Transactions

Repository

Responsible for:

Database queries
Atomic updates
Persistence

This separation makes the system easier to test and maintain.

30. Example Service Architecture

class DeliverySlotService {

    async book({
        customerId,
        orderId,
        preferredSlotId
    }) {

        this.validateRequest({
            customerId,
            orderId,
            preferredSlotId
        });

        const slot =
            await this.slotRepository.findById(
                preferredSlotId
            );

        if (!slot) {
            throw new Error(
                "Delivery slot not found"
            );
        }

        const reservation =
            await this.slotRepository.reserve(
                preferredSlotId,
                customerId,
                orderId
            );

        if (!reservation) {

            const alternatives =
                await this.slotRepository
                    .findAlternatives(
                        preferredSlotId
                    );

            return {
                success: false,
                alternatives
            };
        }

        return {
            success: true,
            reservation
        };
    }
}

The service doesn't need to know the details of SQL or MongoDB.

That's the responsibility of the repository.

31. Key Lessons

The most important lessons from delivery-slot allocation are:

1. Checking availability isn't enough

This:

if (bookedCount < capacity)

doesn't guarantee safe booking under concurrency.

2. Protect the critical section

Use an atomic operation:

UPDATE ...
WHERE booked_count < capacity

3. Use transactions when multiple changes must succeed together

For example:

Reserve capacity
+
Create reservation

4. Handle concurrency explicitly

Assume that multiple users can request the same resource simultaneously.

Don't design the system as if requests are processed one at a time.

5. Provide alternatives

A failed booking doesn't have to mean a bad user experience.

Return useful alternatives.

6. Protect against duplicate requests

Idempotency is important for booking and payment-like operations.

7. Test the race condition

Concurrency bugs often don't appear during normal testing.

Stress the critical operation with simultaneous requests.

32. Final Implementation Strategy

The complete strategy can be summarized as:

Receive Request
       ↓
Validate Input
       ↓
Find Slot
       ↓
Is Slot Valid?
   ↓           ↓
 No           Yes
 ↓             ↓
Error     Atomic Reservation
               ↓
       Reservation Successful?
          ↓             ↓
         No            Yes
         ↓              ↓
 Find Alternatives   Create Reservation
         ↓              ↓
    Return Result    Commit Transaction
                         ↓
                    Booking Success

The core invariant is:

bookedCount <= capacity

And the critical rule is:

Do not separate the availability check
from the capacity update when concurrency matters.

Instead of:

READ
 ↓
CHECK
 ↓
UPDATE

prefer:

CONDITIONAL ATOMIC UPDATE

For example:

UPDATE delivery_slots
SET booked_count = booked_count + 1
WHERE id = ?
AND booked_count < capacity;

Then combine the reservation creation with a transaction when both operations must remain consistent.

Conclusion

Delivery slot allocation may initially look like a simple CRUD operation:

Find slot
→ Check capacity
→ Increment booked count

But once multiple customers can access the same slot concurrently, the problem becomes a concurrency and data-consistency problem.

A robust implementation therefore needs:

Validation
+
Atomic operations
+
Transactions
+
Concurrency control
+
Alternative slots
+
Idempotency
+
Database integrity

The most important principle is simple:

When multiple requests compete for a limited shared resource, the operation that consumes that resource must be concurrency-safe.

This principle goes far beyond delivery slots. It is one of the fundamental ideas behind reliable backend systems.

JavaScript Closures — Part 3 (Engine Internals, Memory Management & Professional Patterns)

Abanoub Kerols — Wed, 26 Aug 2026 06:46:51 +0000

At this point, you already know what closures are and how they work.

Now it's time to understand how the JavaScript engine actually implements closures internally.

This is the level of understanding expected from Senior JavaScript Engineers.

How JavaScript Stores Variables

Whenever JavaScript executes your program, it creates something called an Execution Context.

Each execution context contains several internal components.

Conceptually, it looks like this:

Execution Context

├── Variable Environment
│     ├── count
│     ├── user
│     └── total
│
├── Lexical Environment
│
├── Scope Chain
│
└── this

The important parts for closures are:

Variable Environment
Lexical Environment

What is the Lexical Environment?

A Lexical Environment is an internal data structure used by the JavaScript engine.

Think of it as a dictionary that stores variables.

Example:

function outer() {

    let name = "John";

    let age = 30;

}

Internally, JavaScript stores something conceptually like this:

Lexical Environment

name → "John"

age → 30

Every function gets its own Lexical Environment.

Environment Records

The Lexical Environment itself contains another structure called the Environment Record.

Conceptually:

Lexical Environment

↓

Environment Record

↓

Variables

Example:

function user() {

    let firstName = "John";

    let lastName = "Doe";

}

Environment Record

firstName → John

lastName → Doe

Every variable declared with:

let
const
var
function
class

is stored here.

The Outer Environment Reference

Closures exist because every Lexical Environment keeps a reference to its parent.

Imagine this code.

let country = "Egypt";

function outer() {

    let city = "Cairo";

    function inner() {

        console.log(country);

        console.log(city);

    }

}

Internally

Global Environment

↓

country

↓

Outer Environment

↓

city

↓

Inner Environment

The inner function knows where its parent environment lives.

This relationship forms the Scope Chain.

The Hidden [[Environment]] Property

Every JavaScript function has an internal hidden property.

It isn't accessible from your code.

Conceptually:

Function

↓

[[Environment]]

↓

Lexical Environment

Example

function outer() {

    let score = 50;

    return function () {

        console.log(score);

    };

}

When the inner function is created...

JavaScript stores something like:

Inner Function

↓

[[Environment]]

↓

Outer Lexical Environment

That hidden reference is what makes closures possible.

Step-by-Step Closure Creation

Consider:

function createCounter() {

    let count = 0;

    return function () {

        count++;

        return count;

    };

}

Step 1

createCounter() executes

JavaScript creates:

Execution Context

↓

count = 0

Step 2

The inner function is created.

It secretly stores

[[Environment]]

↓

count

Step 3

The outer function finishes.

Normally:

Variables

↓

Destroyed

But...

JavaScript detects that another function still references them.

Instead of deleting them...

It preserves them.

Step 4

Whenever we call

counter();

The function accesses

count

through its closure.

Why Variables Don't Disappear

Normally:

function test() {

    let x = 10;

}

After execution

x

↓

Garbage Collection

Now compare

function test() {

    let x = 10;

    return function () {

        console.log(x);

    };

}

Now

Returned Function

↓

References x

↓

Garbage Collector

↓

Cannot delete x

Because it is still being used.

Closures and the Garbage Collector

JavaScript uses automatic memory management.

Objects are removed only when nothing references them.

Example

function createUser() {

    let name = "Alice";

    return function () {

        console.log(name);

    };

}

As long as the returned function exists...

The variable

name

cannot be removed.

Once the returned function becomes unreachable...

Everything becomes eligible for garbage collection.

Visualizing Memory

Before

const user = createUser();

Memory

Global

↓

user

↓

Closure

↓

name = Alice

Later

user = null;

Now

Nothing references Closure

Garbage Collector removes everything.

Memory Leaks

Closures themselves are not memory leaks.

The leak happens when we unintentionally keep references alive.

Bad Example

function createHugeArray() {

    const data = new Array(1000000).fill("JavaScript");

    return function () {

        console.log(data.length);

    };

}

Even if we only need the array length...

The entire array remains in memory.

Better

function createHugeArray() {

    const length = new Array(1000000).fill("JS").length;

    return function () {

        return length;

    };

}

Only a number is preserved.

Memory usage becomes much smaller.

Closures and Async Code

Closures become even more important with asynchronous JavaScript.

function fetchUser() {

    let username = "John";

    Promise.resolve().then(function () {

        console.log(username);

    });

}

fetchUser();

Output

John

The Promise callback remembers username.

Closures with async/await

async function loadUser() {

    let id = 10;

    await Promise.resolve();

    console.log(id);

}

loadUser();

Even after the function pauses...

The variables remain available.

The execution context is suspended—not destroyed.

Closures and Higher-Order Functions

A Higher-Order Function either:

accepts another function
returns another function

Closures make this possible.

Example

function multiply(multiplier) {

    return function (number) {

        return multiplier * number;

    };

}

Usage

const double = multiply(2);

const triple = multiply(3);

console.log(double(8));

console.log(triple(8));

Output

16

24

Each returned function owns its own closure.

Currying with Closures

Currying transforms

f(a, b)

into

f(a)(b)

Example

function add(a) {

    return function (b) {

        return a + b;

    };

}

Usage

const addFive = add(5);

console.log(addFive(10));

Output

The value

is preserved by the closure.

Partial Application

Partial Application is closely related.

function calculateTax(rate) {

    return function (price) {

        return price * rate;

    };

}

Usage

const egyptTax = calculateTax(0.14);

console.log(egyptTax(1000));

Output

Very common in Functional Programming.

Dependency Injection Using Closures

Instead of relying on global variables:

const logger = console.log;

Inject dependencies.

function createService(logger) {

    return {

        save(data) {

            logger(data);

        }

    };

}

The logger becomes private.

Testing becomes much easier.

Common Interview Question

What will this print?

function outer() {

    let x = 5;

    return function () {

        console.log(x);

    };

}

const fn = outer();

fn();

Answer

Why?

Because the returned function closes over x.

Another Interview Question

function outer() {

    let x = 10;

    return {

        increment() {

            x++;

        },

        get() {

            return x;

        }

    };

}

const obj = outer();

obj.increment();

obj.increment();

console.log(obj.get());

Output

Both methods share the same closure.

There is only one variable x.

Professional Uses of Closures

Closures power countless production-grade patterns, including:

React Hooks (useState, useMemo, useCallback)
Express Middleware
Redux Middleware
Authentication Wrappers
Logging Utilities
Rate Limiters
Debounce & Throttle Functions
Memoization
Dependency Injection
Function Factories
Plugin Systems
State Management Libraries
Encapsulation and Data Privacy

Understanding closures deeply helps you understand why these tools work the way they do.

Best Practices

✅ Use closures for encapsulation

Keep internal state private and expose only the operations you need.

✅ Prefer `let` and `const`

Modern JavaScript avoids many closure-related bugs that were common with var.

✅ Avoid capturing unnecessary objects

A closure keeps everything it references alive.

Capture only the data you actually need.

✅ Be mindful of memory

Closures are lightweight, but retaining large objects unnecessarily can increase memory usage.

✅ Use closures intentionally

Closures are a powerful abstraction—not just a language feature. They allow you to build cleaner APIs, isolate state, and create reusable behavior without relying on global variables.

Final Thoughts

Closures are one of the defining features of JavaScript.

They are not a trick, nor are they limited to interview questions.

They are a fundamental mechanism that enables many modern JavaScript patterns—from simple callbacks to advanced frameworks like React and backend frameworks like Express.

Once you understand how closures interact with lexical environments, execution contexts, and the garbage collector, you'll be able to reason about JavaScript code more confidently, write safer abstractions, and recognize the patterns used throughout professional codebases.

In many ways, mastering closures is the point where JavaScript starts to feel less like a scripting language and more like a language designed for building sophisticated software systems.

JavaScript Closures — Part 2 (Advanced Concepts & Real-World Applications)

Abanoub Kerols — Fri, 21 Aug 2026 07:03:27 +0000

In the previous part, we learned that a closure is simply:

A function that remembers the variables from the environment where it was created.

Now let's move beyond the basics and see how professional JavaScript developers use closures every day.

Real-World Closures

If you've written JavaScript for a while, you've already used closures—even if you didn't realize it.

Closures appear in:

Event Listeners
Timers (setTimeout, setInterval)
Promises
Async/Await
React Hooks
Express Middleware
Module Pattern
Factory Functions
Memoization
Functional Programming
Currying
Dependency Injection

Closures are one of the foundations of modern JavaScript.

Closures in Event Listeners

Suppose we have a button.

<button id="save">Save</button>

Now imagine this JavaScript:

function setupButton() {

    let clickCount = 0;

    const button = document.getElementById("save");

    button.addEventListener("click", function () {

        clickCount++;

        console.log(`Clicked ${clickCount} times`);

    });

}

setupButton();

Every click increases the counter.

Why?

Because the callback remembers clickCount.

Even after setupButton() has already finished executing.

Memory looks like this:

Event Listener

↓

Closure

↓

clickCount

Without closures, every click would start from zero.

Closures with setTimeout()

One of the easiest ways to see closures is with timers.

function delayedGreeting() {

    let name = "John";

    setTimeout(function () {

        console.log(`Hello ${name}`);

    }, 3000);

}

delayedGreeting();

Output (after 3 seconds)

Hello John

Question:

How does name still exist?

Because the callback function carries a closure.

Even though delayedGreeting() already finished, JavaScript keeps the variable alive.

Closures Inside Loops

One of the most famous interview questions.

Consider this code:

for (var i = 1; i <= 5; i++) {

    setTimeout(function () {

        console.log(i);

    }, 1000);

}

Output

Most beginners expect:

Why?

Because every callback shares the same variable i.

After the loop ends:

i = 6

Every closure references that same variable.

Fix #1 — Using let

for (let i = 1; i <= 5; i++) {

    setTimeout(function () {

        console.log(i);

    }, 1000);

}

Output

Each iteration creates a brand-new variable.

Each closure gets its own copy.

Fix #2 — Using a Closure

Before let existed, developers solved it like this:

for (var i = 1; i <= 5; i++) {

    (function (currentValue) {

        setTimeout(function () {

            console.log(currentValue);

        }, 1000);

    })(i);

}

Each Immediately Invoked Function Expression (IIFE) creates a new closure.

Each callback remembers its own value.

Closures in Factory Functions

Factory functions create objects.

Closures allow every object to have private state.

function createUser(name) {

    return {

        greet() {

            console.log(`Hello ${name}`);

        }

    };

}

const john = createUser("John");

john.greet();

Output

Hello John

Notice that name is completely private.

No one can access it directly.

console.log(john.name);

Output

undefined

Only the closure can access it.

Building a Counter

One of the classic closure examples.

function createCounter() {

    let count = 0;

    return {

        increment() {

            count++;

            return count;

        },

        decrement() {

            count--;

            return count;

        },

        reset() {

            count = 0;

        }

    };

}

const counter = createCounter();

console.log(counter.increment());

console.log(counter.increment());

console.log(counter.decrement());

counter.reset();

console.log(counter.increment());

Output

Notice something important.

There is no way to modify count directly.

Everything must go through the provided methods.

This is true data encapsulation.

Closures and Private Variables

JavaScript didn't originally have private fields.

Developers used closures instead.

function createBankAccount(initialBalance) {

    let balance = initialBalance;

    return {

        deposit(amount) {

            balance += amount;

        },

        withdraw(amount) {

            if (amount <= balance) {

                balance -= amount;

            }

        },

        getBalance() {

            return balance;

        }

    };

}

Usage

const account = createBankAccount(1000);

account.deposit(500);

console.log(account.getBalance());

Output

Trying this:

console.log(account.balance);

Output

undefined

Balance is truly private.

Closures in Express Middleware

Express middleware relies heavily on closures.

function logger(prefix) {

    return function (req, res, next) {

        console.log(prefix, req.method, req.url);

        next();

    };

}

app.use(logger("[API]"));

Here:

prefix

is preserved by the closure.

Every request has access to it.

Closures in React

React Hooks are built around closures.

Example:

function Counter() {

    const [count, setCount] = useState(0);

    function increment() {

        setCount(count + 1);

    }

}

The function remembers the variables from its render.

This explains why stale closures sometimes happen in React.

Example:

setTimeout(() => {

    console.log(count);

}, 5000);

If count changes before five seconds pass...

The callback may still reference the old value.

Understanding closures makes React much easier to understand.

The Once Function

Imagine an expensive initialization process.

You only want it to run once.

function once(fn) {

    let hasRun = false;

    let result;

    return function (...args) {

        if (!hasRun) {

            result = fn(...args);

            hasRun = true;

        }

        return result;

    };

}

Usage

const initialize = once(function () {

    console.log("Initializing...");

    return "Application Ready";

});

console.log(initialize());

console.log(initialize());

console.log(initialize());

Output

Initializing...

Application Ready

Application Ready

Application Ready

Initialization happened exactly one time.

Why Does Once Work?

Memory inside the closure

hasRun = false

result = undefined

First call

↓

Run function

↓

Store result

↓

hasRun = true

Next calls

Skip execution

↓

Return stored result

No global variables.

Everything lives inside the closure.

Building a Memoize Function

Memoization avoids repeating expensive computations.

function memoize(fn) {

    const cache = {};

    return function (...args) {

        const key = JSON.stringify(args);

        if (cache[key]) {

            console.log("Cache Hit");

            return cache[key];

        }

        console.log("Calculating...");

        const result = fn(...args);

        cache[key] = result;

        return result;

    };

}

Usage

const square = memoize(function (number) {

    return number * number;

});

console.log(square(5));

console.log(square(5));

console.log(square(10));

console.log(square(10));

Output

Calculating...

25

Cache Hit

25

Calculating...

100

Cache Hit

100

The cache survives because of the closure.

Without closures, memoization would be impossible.

Module Pattern

Before ES Modules existed, developers used closures for encapsulation.

const UserModule = (function () {

    let users = [];

    function addUser(name) {

        users.push(name);

    }

    function getUsers() {

        return [...users];

    }

    return {

        addUser,

        getUsers

    };

})();

Usage

UserModule.addUser("John");

UserModule.addUser("Alice");

console.log(UserModule.getUsers());

Output

["John", "Alice"]

The internal array cannot be accessed directly.

Everything is hidden inside the closure.

Why Professional Developers Love Closures

Closures provide:

Data Privacy
Encapsulation
State Management
Function Factories
Memoization
Dependency Injection
Functional Programming Patterns
Cleaner APIs
Better Reusability

Many popular JavaScript libraries use closures internally.

If closures disappeared from JavaScript today, React, Vue, Express middleware, Redux utilities, and many modern patterns would become much harder—or impossible—to implement in their current form.

JavaScript Closures — The Complete Guide (From Beginner to Advanced)

Abanoub Kerols — Sun, 16 Aug 2026 06:53:54 +0000

One of the most powerful features in JavaScript isn't a framework, a library, or even a language keyword... it's Closures.

Closures are everywhere.

Every React Hook, every Express middleware, every event listener, every callback, every memoization function, every module pattern, and many advanced JavaScript libraries rely heavily on closures.

Yet, many developers memorize the definition without truly understanding what happens behind the scenes.

In this guide, we'll build an intuitive understanding of JavaScript Closures from scratch, explore how JavaScript stores variables, understand lexical scope, dive into execution contexts, and finally build production-ready examples used by professional software engineers.

What is a Closure?
Why Closures Exist
JavaScript Functions are First-Class Objects
Lexical Scope
Scope Chain
Execution Context
The Call Stack
Functions Remember Their Environment
The Backpack Analogy
Closed Over Variables
Returning Functions
Persistent State
Multiple Independent Closures
Real World Examples
Once Function
Memoization
Module Pattern
Common Mistakes
Performance Considerations
Best Practices
Conclusion

What is a Closure?

The official definition from MDN says:

A closure is a function bundled together with references to its surrounding lexical environment.

Although technically correct...

It doesn't really explain what is happening.

A much simpler definition is:

A Closure is a function that remembers the variables that existed when it was created—even after the outer function has already finished executing.

That's it.

The keyword here is remembers.

Why Do Closures Exist?

Normally, local variables disappear after a function finishes.

Example:

function hello() {
    let message = "Hello";
}

hello();

// message no longer exists
console.log(message);

Output

ReferenceError

The variable lived only inside hello().

After execution finished...

Memory should have been released.

So why does this work?

function outer() {

    let message = "Hello";

    function inner() {
        console.log(message);
    }

    return inner;
}

const fn = outer();

fn();

Output

Hello

How?

The outer function already finished.

Its variables should have disappeared.

But they didn't.

Because of Closure.

JavaScript Functions are More Than Code

Many developers think a function is only executable code.

Actually, a JavaScript function is an object.

It contains:

executable code
name
parameters
internal properties
reference to where it was created

Conceptually:

Function Object

{
    code: ...
    name: "inner"
    [[Environment]] ---> Outer Scope
}

That hidden reference is the secret behind closures.

Lexical Scope

Closures cannot exist without understanding lexical scope.

Lexical means:

Determined by where the code is written.

Example

let language = "JavaScript";

function printLanguage() {
    console.log(language);
}

printLanguage();

Output

JavaScript

The function looks upward through its surrounding scopes.

Not where it is called.

Where it is defined.

Example:

let value = 10;

function outer() {

    let value = 20;

    function inner() {
        console.log(value);
    }

    return inner;
}

const fn = outer();

fn();

Output

Not 10.

Because inner() was defined inside outer().

Scope Chain

Whenever JavaScript cannot find a variable...

It walks upward.

Current Scope

↓

Outer Scope

↓

Global Scope

↓

null

Example

let country = "Egypt";

function one() {

    function two() {

        function three() {
            console.log(country);
        }

        three();
    }

    two();
}

one();

JavaScript searches:

three()

↓

two()

↓

one()

↓

Global

Eventually finds

country

Execution Context

Every function call creates an Execution Context.

It contains

Variables
Parameters
this
Scope Reference

Example

function multiply(a, b) {

    let result = a * b;

    return result;
}

multiply(5, 6);

Execution Context

multiply

a = 5

b = 6

result = 30

Normally...

After the function returns...

Everything disappears.

Except...

If another function still needs it.

That's Closure.

The Call Stack

Consider

function one() {
    two();
}

function two() {
    three();
}

function three() {
    console.log("Done");
}

one();

Call Stack

three()

two()

one()

Global

After finishing

Global

Everything pops off the stack.

Normally memory disappears.

Closures change this behavior.

Functions Have Permanent Memories

Imagine this code.

function createGreeting() {

    let greeting = "Hello";

    return function () {
        console.log(greeting);
    };
}

const greet = createGreeting();

greet();

Output

Hello

Even though

createGreeting()

already finished...

Its variable still exists.

Why?

Because the returned function still references it.

The Backpack Analogy

One of the best mental models for closures is the Backpack.

Imagine every function carries a backpack.

Inside the backpack...

JavaScript stores every variable the function might need later.

Example

function outer() {

    let count = 0;

    return function () {

        count++;

        console.log(count);

    };

}

Backpack

count = 0

Every time the function executes

count

is still there.

Output

The variable never resets because it lives inside the closure.

Closed Over Variables

Variables preserved by closures are called

Closed Over Variables

Example

function counter() {

    let value = 0;

    return function () {

        value++;

        return value;

    };

}

Here

value

is a closed over variable.

It survives every function call.

Returning Functions

Closures become useful when returning functions.

function multiplyBy(x) {

    return function(y) {
        return x * y;
    };

}

const double = multiplyBy(2);

const triple = multiplyBy(3);

console.log(double(8));

console.log(triple(8));

Output

16

24

Each returned function remembers its own value of x.

Persistent State

Without Closure

let count = 0;

function increment() {

    count++;

}

Global variables are dangerous.

With Closure

function createCounter() {

    let count = 0;

    return function() {

        count++;

        return count;

    };

}

Everything becomes private.

No global pollution.

Much safer.

Multiple Independent Closures

Every call creates a completely independent closure.

const counterA = createCounter();

const counterB = createCounter();

Memory

counterA

count = 0

Memory

counterB

count = 0

Now

console.log(counterA());

console.log(counterA());

console.log(counterB());

console.log(counterB());

console.log(counterA());

Output

Each function owns its own memory.

This is one of the most important concepts in closures.

Finite State Machines: A Complete Guide from Fundamentals to Production

Abanoub Kerols — Tue, 11 Aug 2026 07:11:24 +0000

Finite State Machines (FSMs) are one of the most useful concepts in computer science and software engineering.

They provide a structured way to model systems that behave differently depending on their current state and the events they receive.

You can find state machines everywhere:

Authentication systems
Payment processing
Order management
HTTP requests
WebSocket connections
Retry mechanisms
Background jobs
Video players
Game engines
Traffic lights
Elevators
Vending machines
Embedded systems
UI components
Distributed systems
Event-driven architectures

Despite being a relatively simple concept, State Machines become extremely powerful when used to model complex business workflows.

This article starts from the fundamentals and gradually moves toward advanced concepts, implementation techniques, software architecture, and finally a production-oriented Node.js + TypeScript project.

Part 1 — Fundamentals
Part 2 — Finite State Machines
Part 3 — FSM Design
Part 4 — FSM Implementation
Part 5 — Advanced FSM
Part 6 — Real-World Applications
Part 7 — FSM + Modern Software Architecture
Part 8 — Production Project
Conclusion

Part 1 — Fundamentals

What Is a State Machine?

A State Machine is a mathematical and software model used to represent a system that can exist in different states and change between those states when events occur.

The basic idea is:

Current State
      +
    Event
      |
      v
  Transition
      |
      v
   New State

For example, imagine an online order.

An order might have the following states:

PENDING
PAID
PROCESSING
SHIPPED
DELIVERED
CANCELLED

The order changes state when events occur.

For example:

PENDING + PAY
        ↓
       PAID

PAID + START_PROCESSING
        ↓
    PROCESSING

PROCESSING + SHIP
        ↓
     SHIPPED

SHIPPED + DELIVER
        ↓
    DELIVERED

The important idea is that the system's behavior depends on its current state.

Why Do We Need State Machines?

Without a State Machine, developers often implement workflows using large collections of:

if
else if
else

For example:

if (order.status === "pending") {
    if (event === "pay") {
        ...
    }
}

if (order.status === "paid") {
    if (event === "ship") {
        ...
    }
}

As the system grows, this can become difficult to understand.

Eventually we may end up with:

if
 ├── if
 │    ├── if
 │    └── if
 ├── else if
 │    ├── if
 │    └── if
 └── else if
      ├── if
      └── if

State Machines provide explicit structure.

Instead of asking:

"What should this giant function do?"

we ask:

"What states exist, what events can occur, and which transitions are allowed?"

This makes the system easier to:

Understand
Test
Debug
Maintain
Document
Extend
Validate

The Concept of State

A State represents the current condition of a system.

For example:

Order:
PENDING

means the order has been created but has not been paid.

Another state:

PAID

means payment has successfully completed.

Another:

SHIPPED

means the order has been handed over to the shipping process.

A state is therefore a snapshot of the system's current mode of behavior.

The Concept of Event / Input

An Event is something that happens and may cause a state transition.

Examples:

PAY
CANCEL
SHIP
DELIVER
TIMEOUT
RETRY
LOGIN
LOGOUT
DISCONNECT
CONNECT

For example:

State: PENDING

Event: PAY

The machine may transition to:

PAID

An event can come from many sources:

HTTP requests
User actions
Database events
Message queues
Timers
WebSocket messages
External services
Internal application logic

The Concept of Transition

A Transition describes how the machine moves from one state to another.

Conceptually:

FROM STATE
     |
   EVENT
     |
     v
TO STATE

Example:

PENDING --PAY--> PAID

Another example:

PAID --START_PROCESSING--> PROCESSING

A transition can also have conditions and actions.

PENDING
   |
   | PAY
   | [payment successful]
   v
PAID

The Concept of Action

An Action is something the system performs when a transition occurs.

For example:

PENDING --PAY--> PAID

The transition may execute:

sendPaymentConfirmation();

or:

createInvoice();

or:

publishOrderPaidEvent();

Actions are usually side effects.

Examples:

Send an email
Write to a database
Publish an event
Call an API
Create a log
Start a job

A useful distinction is:

State       = Where am I?
Event       = What happened?
Transition  = Where can I go?
Guard       = Am I allowed to go there?
Action      = What should I do?

State Diagram

A State Diagram visually represents the State Machine.

For example:

             PAY
   +------------------------+
   |                        v
+---------+             +--------+
| PENDING | ------------> | PAID |
+---------+             +--------+
    |                       |
    | CANCEL                | SHIP
    v                       v
+-----------+          +----------+
| CANCELLED |          |  SHIPPED |
+-----------+          +----------+
                             |
                             | DELIVER
                             v
                        +-----------+
                        | DELIVERED |
                        +-----------+

A state diagram makes the workflow much easier to understand.

A Simple Practical Example

Let's build a simple light switch.

The light can have two states:

OFF
ON

Events:

TURN_ON
TURN_OFF

Transitions:

OFF --TURN_ON--> ON
ON  --TURN_OFF--> OFF

Diagram:

       TURN_ON
 OFF ------------> ON
  ^                 |
  |                 |
  +--- TURN_OFF ----+

Implementation:

let state = "OFF";

function dispatch(event) {
    if (state === "OFF" && event === "TURN_ON") {
        state = "ON";
        return;
    }

    if (state === "ON" && event === "TURN_OFF") {
        state = "OFF";
        return;
    }

    throw new Error(`Invalid transition: ${state} + ${event}`);
}

Usage:

dispatch("TURN_ON");

console.log(state);
// ON

dispatch("TURN_OFF");

console.log(state);
// OFF

Even this tiny example demonstrates the fundamental concept.

Part 2 — Finite State Machines

Definition of a Finite State Machine

A Finite State Machine is a mathematical model consisting of a finite number of states and rules describing how the machine moves between those states based on input symbols.

A classical FSM can be represented as:

FSM = (Q, Σ, δ, q₀, F)

Where:

Q  = Set of states
Σ  = Set of input symbols
δ  = Transition function
q₀ = Initial state
F  = Set of accepting/final states

Let's understand each component.

Components of an FSM

Consider:

States:
PENDING
PAID
SHIPPED
DELIVERED

Then:

Q = {
    PENDING,
    PAID,
    SHIPPED,
    DELIVERED
}

Events form the input alphabet:

Σ = {
    PAY,
    SHIP,
    DELIVER
}

The transition function determines where the machine goes.

For example:

δ(PENDING, PAY) = PAID
δ(PAID, SHIP) = SHIPPED
δ(SHIPPED, DELIVER) = DELIVERED

The initial state is:

q₀ = PENDING

Accepting states might be:

F = {
    DELIVERED
}

Transition Function

The transition function is one of the most important concepts in FSMs.

It can be expressed as:

δ(currentState, event) = nextState

Example:

δ(PENDING, PAY) = PAID

Meaning:

If the current state is PENDING and the PAY event occurs, transition to PAID.

Another:

δ(PAID, SHIP) = SHIPPED

Initial State

The Initial State is where the machine starts.

For an order:

PENDING

For authentication:

LOGGED_OUT

For a WebSocket:

DISCONNECTED

For a payment:

CREATED

The initial state is usually represented using an arrow:

        +---------+
        | PENDING |
        +---------+
             ^
             |
           START

Final / Accepting States

A final state represents a state where the process can be considered complete.

For example:

ORDER_CREATED
     |
     v
PAID
     |
     v
SHIPPED
     |
     v
DELIVERED

Here:

DELIVERED

could be an accepting state.

However, in software engineering, not every FSM necessarily needs a final state.

For example, a WebSocket connection can continuously move between:

CONNECTED
DISCONNECTED
RECONNECTING

without ever reaching a permanent final state.

Deterministic Finite Automaton — DFA

A Deterministic Finite Automaton has exactly one possible transition for a given:

State + Input

That means:

δ(state, input) = exactly one state

For example:

PENDING + PAY → PAID

There cannot be two different outcomes for the same input.

This makes DFA behavior predictable.

Non-Deterministic Finite Automaton — NFA

A Non-Deterministic Finite Automaton can have multiple possible transitions for the same state and input.

Conceptually:

δ(state, input) → {state1, state2, ...}

For example:

A + X
 ├──> B
 └──> C

NFAs are particularly important in theoretical computer science, formal languages, regular expressions, and compiler design.

In normal application development, developers usually implement deterministic state machines because business workflows typically require predictable behavior.

DFA vs NFA

Feature	DFA	NFA
One transition per input	Yes	Not necessarily
Multiple possible states	No	Yes
Deterministic	Yes	No
Easier to execute	Yes	Usually more complex
Common in business applications	Yes	Less common
Used in theoretical CS	Yes	Yes

An important theoretical fact is that DFA and NFA have equivalent expressive power for regular languages.

Every NFA can be converted into an equivalent DFA.

Moore Machine

A Moore Machine is a finite-state machine where the output depends primarily on the current state.

Output = f(State)

For example:

State: RED
Output: STOP

State: GREEN
Output: GO

Diagram:

RED
 |
 | TIMER
 v
GREEN
 |
 | TIMER
 v
YELLOW

The output is associated with the state.

Mealy Machine

A Mealy Machine produces output based on both:

State + Input

Formally:

Output = f(State, Input)

For example:

State: LOCKED
Input: VALID_PASSWORD
Output: UNLOCK

This differs from a Moore Machine where the output is associated with the state itself.

Moore vs Mealy

Feature	Moore	Mealy
Output depends on	State	State + Input
Output associated with	State	Transition
Response timing	Often state change	Can react immediately
Complexity	Often simpler	Often more compact

In real-world software, you may encounter patterns inspired by both models.

Part 3 — FSM Design

How to Design an FSM from Requirements

A common mistake is to start coding immediately.

Instead, start with requirements.

Suppose we have:

A customer creates an order. The order can be paid, cancelled, shipped, delivered, or refunded.

We can derive the machine systematically.

Step 1 — Extract the States

Look for nouns or lifecycle conditions.

Possible states:

PENDING
PAID
PROCESSING
SHIPPED
DELIVERED
CANCELLED
REFUNDED

Step 2 — Extract Events

Look for actions or things that happen.

PAY
START_PROCESSING
SHIP
DELIVER
CANCEL
REFUND

Step 3 — Design Transitions

Now connect states and events.

PENDING + PAY
    ↓
PAID

PAID + START_PROCESSING
    ↓
PROCESSING

PROCESSING + SHIP
    ↓
SHIPPED

SHIPPED + DELIVER
    ↓
DELIVERED

Step 4 — Add Guards

Sometimes an event alone is not enough.

For example:

PENDING + PAY

does not necessarily mean the order becomes paid.

We may require:

payment.status === "SUCCESS"

Therefore:

PENDING
   |
   | PAY
   | [payment successful]
   v
PAID

The condition is called a Guard.

Example:

if (payment.status === "SUCCESS") {
    transitionTo("PAID");
}

Step 5 — Add Actions

The transition may execute side effects.

PENDING
   |
   | PAY
   |
   +--> updateOrder()
   +--> createInvoice()
   +--> sendEmail()
   +--> publishEvent()
   |
   v
PAID

Invalid Transitions

A State Machine should explicitly define what happens when an invalid event occurs.

For example:

DELIVERED + PAY

does not make sense.

Possible behavior:

throw new Error("Invalid transition");

Or:

return {
    success: false,
    error: "INVALID_TRANSITION"
};

Explicit invalid transitions are important because they prevent impossible states.

State Invariants

A State Invariant is a rule that must always be true while the machine is in a specific state.

For example:

PAID

might require:

paymentId != null

while:

SHIPPED

might require:

trackingNumber != null

Example:

if (state === "SHIPPED") {
    if (!order.trackingNumber) {
        throw new Error(
            "Shipped orders must have a tracking number"
        );
    }
}

Invariants are extremely useful for maintaining domain correctness.

State Explosion Problem

One of the biggest problems with State Machines is state explosion.

Imagine a system with:

Authentication
Payment
Shipping
Inventory
Fraud Detection
Notification

If every combination becomes a state, the number of states can become enormous.

For example:

PAYMENT_PENDING
PAYMENT_SUCCESS
PAYMENT_FAILED
PAYMENT_RETRYING

SHIPPING_PENDING
SHIPPING_PROCESSING
SHIPPING_FAILED
...

Combining everything can create hundreds or thousands of states.

This is called the:

State Explosion Problem

Solutions include:

Hierarchical State Machines
Composite States
Parallel States
Separating independent state machines
Domain decomposition
Statecharts
Event-driven architecture

Part 4 — FSM Implementation

There are many ways to implement an FSM.

FSM Using if/else

The simplest approach:

function transition(
    state: string,
    event: string
): string {

    if (state === "PENDING" && event === "PAY") {
        return "PAID";
    }

    if (state === "PAID" && event === "SHIP") {
        return "SHIPPED";
    }

    if (state === "SHIPPED" && event === "DELIVER") {
        return "DELIVERED";
    }

    throw new Error("Invalid transition");
}

This works well for very small machines.

However, it becomes difficult to maintain when the machine grows.

FSM Using switch

Another common approach:

function transition(
    state: string,
    event: string
): string {

    switch (state) {

        case "PENDING":
            if (event === "PAY") {
                return "PAID";
            }
            break;

        case "PAID":
            if (event === "SHIP") {
                return "SHIPPED";
            }
            break;

        case "SHIPPED":
            if (event === "DELIVER") {
                return "DELIVERED";
            }
            break;
    }

    throw new Error("Invalid transition");
}

This is clearer than deeply nested conditions.

But it still mixes:

State Definition
Transition Definition
Business Logic

FSM Using Objects

We can represent transitions as data.

const transitions = {
    PENDING: {
        PAY: "PAID",
    },

    PAID: {
        SHIP: "SHIPPED",
    },

    SHIPPED: {
        DELIVER: "DELIVERED",
    }
};

Then:

function transition(
    state: string,
    event: string
) {
    const nextState =
        transitions[state]?.[event];

    if (!nextState) {
        throw new Error(
            `Invalid transition: ${state} + ${event}`
        );
    }

    return nextState;
}

This approach separates configuration from execution.

FSM Using Maps

JavaScript and TypeScript Maps are useful when we want structured keys.

const transitions = new Map<string, Map<string, string>>();

transitions.set(
    "PENDING",
    new Map([
        ["PAY", "PAID"]
    ])
);

transitions.set(
    "PAID",
    new Map([
        ["SHIP", "SHIPPED"]
    ])
);

Then:

function transition(
    state: string,
    event: string
) {
    const nextState =
        transitions.get(state)?.get(event);

    if (!nextState) {
        throw new Error("Invalid transition");
    }

    return nextState;
}

Table-Driven FSM

A Table-Driven FSM represents the machine as a transition table.

Current State	Event	Next State
PENDING	PAY	PAID
PAID	PROCESS	PROCESSING
PROCESSING	SHIP	SHIPPED
SHIPPED	DELIVER	DELIVERED
PENDING	CANCEL	CANCELLED

This approach is particularly useful when the number of transitions is large.

The FSM engine can remain generic while the table contains domain-specific behavior.

Generic FSM

A reusable FSM engine might look like:

type Transition<State, Event> = {
    target: State;
    action?: () => void;
};

class FSM<State extends string, Event extends string> {

    private state: State;

    constructor(
        initialState: State,
        private transitions:
            Map<State, Map<Event, Transition<State, Event>>>
    ) {
        this.state = initialState;
    }

    getState(): State {
        return this.state;
    }

    dispatch(event: Event): void {

        const transition =
            this.transitions
                .get(this.state)
                ?.get(event);

        if (!transition) {
            throw new Error(
                `Invalid transition: ${this.state} + ${event}`
            );
        }

        transition.action?.();

        this.state = transition.target;
    }
}

Now the engine is reusable for different domains.

TypeScript FSM

TypeScript becomes particularly useful because states and events can be represented as union types.

type OrderState =
    | "PENDING"
    | "PAID"
    | "PROCESSING"
    | "SHIPPED"
    | "DELIVERED"
    | "CANCELLED";

type OrderEvent =
    | "PAY"
    | "PROCESS"
    | "SHIP"
    | "DELIVER"
    | "CANCEL";

Now TypeScript can prevent invalid values.

Example:

let state: OrderState = "PENDING";

Java FSM

A Java implementation can use enums.

enum OrderState {
    PENDING,
    PAID,
    PROCESSING,
    SHIPPED,
    DELIVERED,
    CANCELLED
}

enum OrderEvent {
    PAY,
    PROCESS,
    SHIP,
    DELIVER,
    CANCEL
}

Then:

public OrderState transition(
    OrderState state,
    OrderEvent event
) {

    return switch (state) {

        case PENDING -> {
            if (event == OrderEvent.PAY)
                yield OrderState.PAID;

            if (event == OrderEvent.CANCEL)
                yield OrderState.CANCELLED;

            throw new IllegalStateException();
        }

        case PAID -> {
            if (event == OrderEvent.PROCESS)
                yield OrderState.PROCESSING;

            throw new IllegalStateException();
        }

        default ->
            throw new IllegalStateException(
                "Invalid transition"
            );
    };
}

Python FSM

Python can implement a simple FSM using dictionaries.

transitions = {
    "PENDING": {
        "PAY": "PAID",
        "CANCEL": "CANCELLED"
    },

    "PAID": {
        "PROCESS": "PROCESSING"
    },

    "PROCESSING": {
        "SHIP": "SHIPPED"
    },

    "SHIPPED": {
        "DELIVER": "DELIVERED"
    }
}

Then:

def transition(state, event):

    next_state = transitions \
        .get(state, {}) \
        .get(event)

    if next_state is None:
        raise ValueError(
            f"Invalid transition: {state} + {event}"
        )

    return next_state

Part 5 — Advanced FSM

Hierarchical State Machines

A Hierarchical State Machine allows states to contain sub-states.

For example:

AUTHENTICATED
├── ACTIVE
├── IDLE
└── LOCKED

Instead of treating every state independently, we can create a hierarchy.

Example:

USER
 ├── LOGGED_OUT
 └── LOGGED_IN
      ├── ACTIVE
      ├── IDLE
      └── LOCKED

This reduces duplication.

Nested States

Nested states allow one state to contain other states.

For example:

ORDER
 ├── PAYMENT
 │    ├── PENDING
 │    ├── PROCESSING
 │    └── SUCCESS
 │
 └── SHIPPING
      ├── PENDING
      ├── SHIPPED
      └── DELIVERED

This is especially useful for complex workflows.

Composite States

A Composite State is a state that internally contains another state machine.

For example:

CHECKOUT

could contain:

CART
ADDRESS
PAYMENT
CONFIRMATION

So:

CHECKOUT
   |
   +-- CART
   |
   +-- ADDRESS
   |
   +-- PAYMENT
   |
   +-- CONFIRMATION

Parallel States

Sometimes multiple processes need to happen independently.

For example, an order might simultaneously have:

Payment:
SUCCESS

Shipping:
PROCESSING

Notification:
SENDING

Instead of creating:

PAYMENT_SUCCESS_SHIPPING_PROCESSING_NOTIFICATION_SENDING

we can use parallel state machines.

Conceptually:

ORDER
 |
 +---- PAYMENT
 |
 +---- SHIPPING
 |
 +---- NOTIFICATION

Each subsystem has its own state.

This dramatically reduces state explosion.

History States

History states allow a machine to remember its previous state.

Example:

ACTIVE
 ├── BROWSING
 ├── CHECKOUT
 └── PAYMENT

Suppose the user leaves the application while in:

PAYMENT

When they return, the system can restore:

PAYMENT

instead of restarting from:

BROWSING

This concept is useful in:

UI workflows
Games
Long-running processes
Distributed workflows

Entry Actions

An Entry Action runs when entering a state.

Example:

ENTER PAID
    ↓
createInvoice()

Conceptually:

const paidState = {
    entry: () => {
        createInvoice();
    }
};

Exit Actions

An Exit Action runs when leaving a state.

LEAVE PROCESSING
       ↓
cleanupProcessing()

Example:

const processingState = {
    exit: () => {
        cleanupProcessing();
    }
};

Guards

Guards are conditions that determine whether a transition is allowed.

Example:

PENDING
   |
   | PAY
   | [amount > 0]
   v
PAID

Implementation:

{
    event: "PAY",
    target: "PAID",
    guard: context => context.amount > 0
}

Guards are useful for:

Authorization
Validation
Payment checks
Inventory checks
Feature flags
Business rules

Internal Transitions

An Internal Transition handles an event without changing state.

Example:

CONNECTED
   |
   | HEARTBEAT
   |
   +----> CONNECTED

The state remains:

CONNECTED

but an action occurs:

heartbeat();

Event Queues

Events do not always need to be processed immediately.

A system may receive:

PAY
SHIP
DELIVER

very quickly.

An event queue can process them sequentially:

Event Queue

PAY
 ↓
SHIP
 ↓
DELIVER

This can help prevent race conditions.

State Persistence

If the application restarts, in-memory state disappears.

For long-running workflows, state may need to be persisted.

For example:

Database

order_id: 123
state: PAYMENT_PENDING
version: 7

When the service restarts:

Database
   ↓
Load state
   ↓
Restore FSM

Persistence is essential for production workflows.

Part 6 — Real-World Applications

Authentication

Authentication is naturally modeled using states.

LOGGED_OUT
     |
     | LOGIN
     v
AUTHENTICATING
     |
     | SUCCESS
     v
AUTHENTICATED
     |
     | LOGOUT
     v
LOGGED_OUT

Additional states:

LOCKED
MFA_REQUIRED
SESSION_EXPIRED

Order Processing

Typical order lifecycle:

CREATED
   ↓
PENDING_PAYMENT
   ↓
PAID
   ↓
PROCESSING
   ↓
SHIPPED
   ↓
DELIVERED

Alternative path:

PENDING_PAYMENT
       |
       | CANCEL
       v
   CANCELLED

Payment Processing

Payment systems commonly have:

CREATED
PENDING
PROCESSING
AUTHORIZED
CAPTURED
FAILED
REFUNDED

Example:

CREATED
   |
   | PROCESS
   v
PROCESSING
   |
   +---- SUCCESS ---> AUTHORIZED
   |
   +---- FAILURE ---> FAILED

E-Commerce Checkout

Checkout can be modeled as:

CART
 ↓
ADDRESS
 ↓
SHIPPING
 ↓
PAYMENT
 ↓
CONFIRMATION

If payment fails:

PAYMENT
   |
   | FAILURE
   v
PAYMENT_ERROR
   |
   | RETRY
   v
PAYMENT

HTTP Request Lifecycle

An HTTP request can conceptually move through:

RECEIVED
   ↓
VALIDATING
   ↓
AUTHENTICATING
   ↓
PROCESSING
   ↓
RESPONDING
   ↓
COMPLETED

Error paths:

VALIDATING
   |
   | INVALID
   v
BAD_REQUEST

AUTHENTICATING
   |
   | FAILURE
   v
UNAUTHORIZED

WebSocket Connection

WebSocket lifecycle is another excellent example.

DISCONNECTED
      |
      | CONNECT
      v
CONNECTING
      |
      | SUCCESS
      v
CONNECTED
      |
      | DISCONNECT
      v
DISCONNECTED

Failure path:

CONNECTING
     |
     | ERROR
     v
RECONNECTING

Retry Systems

Retry logic can be modeled explicitly.

IDLE
 ↓
RUNNING
 ↓
FAILED
 ↓
RETRYING
 ↓
RUNNING

Eventually:

RETRYING
   |
   | MAX_RETRIES
   v
PERMANENT_FAILURE

This is much safer than scattering retry counters across multiple functions.

Job Processing

A background job might use:

QUEUED
 ↓
PROCESSING
 ↓
COMPLETED

Failure:

PROCESSING
   |
   | FAILURE
   v
FAILED
   |
   | RETRY
   v
QUEUED

Game Development

Game characters can be modeled using:

IDLE
RUNNING
JUMPING
ATTACKING
HURT
DEAD

For example:

IDLE
 |
 | MOVE
 v
RUNNING
 |
 | JUMP
 v
JUMPING

This is a classic application of FSMs.

Traffic Lights

A traffic light is one of the simplest FSM examples.

RED
 ↓
GREEN
 ↓
YELLOW
 ↓
RED

The event could be:

TIMER_EXPIRED

Elevator

An elevator can have:

IDLE
MOVING_UP
MOVING_DOWN
DOOR_OPENING
DOOR_OPEN
DOOR_CLOSING
EMERGENCY

Transitions depend on:

Floor requests
Door sensors
Emergency signals
Movement completion

Vending Machine

A vending machine might have:

IDLE
COIN_INSERTED
PRODUCT_SELECTED
PAYMENT_COMPLETE
DISPENSING
OUT_OF_STOCK

Example:

IDLE
 |
 | INSERT_COIN
 v
COIN_INSERTED
 |
 | SELECT_PRODUCT
 v
PRODUCT_SELECTED
 |
 | PAYMENT_OK
 v
DISPENSING
 |
 | COMPLETE
 v
IDLE

Embedded Systems

FSMs are extremely common in embedded systems because embedded devices often have well-defined operating modes.

Examples:

BOOT
INITIALIZING
READY
RUNNING
ERROR
SHUTDOWN

Hardware controllers often depend heavily on explicit state transitions.

Part 7 — FSM + Modern Software Architecture

FSM + OOP

Object-Oriented Programming can model states using classes.

For example:

interface State {
    handle(event: Event): State;
}

Then:

class PendingState implements State {
    handle(event: Event): State {
        if (event === "PAY") {
            return new PaidState();
        }

        throw new Error("Invalid event");
    }
}

This is known as the State Pattern.

FSM + Functional Programming

Functional Programming can model transitions as pure functions.

function transition(
    state: State,
    event: Event
): State {
    ...
}

A pure transition function:

State + Event
      ↓
   New State

has no hidden side effects.

This makes testing very easy.

For example:

expect(
    transition("PENDING", "PAY")
).toBe("PAID");

Functional FSMs are particularly useful when combined with immutable state.

FSM + Event-Driven Architecture

In an Event-Driven Architecture, events drive state transitions.

For example:

PaymentCompleted
        |
        v
Order FSM
        |
        v
PAID

Then:

OrderPaid
    |
    +--> Notification Service
    |
    +--> Shipping Service
    |
    +--> Analytics Service

The State Machine controls the lifecycle while events connect different components.

FSM + Event Sourcing

Event Sourcing stores events instead of only storing the current state.

Instead of:

Order:
state = SHIPPED

we store:

OrderCreated
PaymentCompleted
ProcessingStarted
OrderShipped

The current state can be reconstructed by replaying events:

Initial State
     ↓
OrderCreated
     ↓
PaymentCompleted
     ↓
ProcessingStarted
     ↓
OrderShipped
     ↓
Current State = SHIPPED

This makes FSMs a natural fit for Event Sourcing.

FSM + CQRS

CQRS separates:

Commands

from:

Queries

A command can cause an FSM transition.

For example:

ShipOrderCommand
        |
        v
Order FSM
        |
        v
SHIPPED

The resulting state can then be exposed through the query side.

FSM + Distributed Systems

Distributed systems introduce additional challenges:

Network failures
Duplicate messages
Out-of-order events
Retries
Partial failures
Concurrent updates

FSMs can help define valid lifecycle transitions.

For example:

PENDING
   |
   | PAYMENT_COMPLETED
   v
PAID

If the same event arrives twice:

PAYMENT_COMPLETED
PAYMENT_COMPLETED

the second event should not create an invalid state.

This is where idempotency becomes critical.

FSM + Microservices

A microservice may own its own state machine.

For example:

Order Service
    |
    +-- Order FSM

Payment Service
    |
    +-- Payment FSM

Shipping Service
    |
    +-- Shipping FSM

Instead of one giant FSM:

Order + Payment + Shipping + Inventory

we can create several smaller machines.

This helps reduce state explosion and improves service boundaries.

FSM + Redux

Redux applications already use a state-transition model.

Conceptually:

State + Action
      ↓
   Reducer
      ↓
  New State

This is very similar to an FSM:

State + Event
      ↓
 Transition
      ↓
 New State

The key difference is that Redux is a general state-management architecture, while an FSM explicitly defines legal states and transitions.

FSM + Angular

Angular applications can benefit from FSMs for complex UI workflows.

For example:

IDLE
 |
 | SUBMIT
 v
SUBMITTING
 |
 +---- SUCCESS ---> SUCCESS
 |
 +---- ERROR -----> ERROR

This is much cleaner than maintaining several independent booleans:

isLoading
isSuccess
isError
isSubmitted

Boolean combinations can accidentally create impossible states.

For example:

isLoading = true
isSuccess = true
isError = true

An FSM prevents these invalid combinations.

FSM + RxJS

RxJS is especially useful for event streams.

For example:

events$
    .pipe(
        scan(
            (state, event) =>
                transition(state, event),
            "IDLE"
        )
    );

Conceptually:

Event Stream
     |
     v
RxJS scan()
     |
     v
FSM Transition
     |
     v
State Stream

This is a powerful combination for reactive applications.

FSM + XState

XState is a popular library for implementing state machines and statecharts.

A machine can be described declaratively:

const orderMachine = createMachine({
    initial: "pending",

    states: {
        pending: {
            on: {
                PAY: "paid"
            }
        },

        paid: {
            on: {
                SHIP: "shipped"
            }
        },

        shipped: {
            on: {
                DELIVER: "delivered"
            }
        },

        delivered: {}
    }
});

The advantage is that the state machine becomes explicit and declarative.

XState also supports advanced concepts such as:

Hierarchical states
Parallel states
Guards
Actions
Delays
Actors
State persistence

Part 8 — Production Project

Now let's design a production-oriented Order State Machine using:

Node.js
TypeScript
Express.js
PostgreSQL
Redis

The goal is not simply to demonstrate an FSM.

The goal is to design something closer to a real backend system.

Project Requirements

Our order system should support:

Creating orders
Paying orders
Processing orders
Shipping orders
Delivering orders
Cancelling orders
Retrying failures
Persisting state
Idempotency
Concurrency protection
Testing
Logging
Observability

Architecture

A possible architecture:

                    Client
                      |
                      v
                 Express API
                      |
                      v
                Order Service
                      |
             +--------+--------+
             |                 |
             v                 v
        Order FSM           Redis
             |
             v
         PostgreSQL
             |
             v
        Event Publisher
             |
       +-----+------+
       |            |
       v            v
 Notification    Shipping
 Service         Service

Order States

Let's define:

export enum OrderState {
    PENDING_PAYMENT = "PENDING_PAYMENT",
    PAID = "PAID",
    PROCESSING = "PROCESSING",
    SHIPPED = "SHIPPED",
    DELIVERED = "DELIVERED",
    CANCELLED = "CANCELLED",
    FAILED = "FAILED"
}

Order Events

export enum OrderEvent {
    PAYMENT_COMPLETED = "PAYMENT_COMPLETED",
    START_PROCESSING = "START_PROCESSING",
    SHIP = "SHIP",
    DELIVER = "DELIVER",
    CANCEL = "CANCEL",
    FAILURE = "FAILURE",
    RETRY = "RETRY"
}

Order Context

The FSM should not contain all application data inside the state itself.

We can use a Context object:

export interface OrderContext {
    orderId: string;
    customerId: string;
    amount: number;

    paymentId?: string;
    trackingNumber?: string;

    retryCount: number;
}

The state answers:

What stage is the order in?

The context answers:

What data belongs to this order?

This separation is extremely useful.

Transition Definition

We can define transitions using configuration.

interface Transition {
    target: OrderState;

    guard?: (
        context: OrderContext
    ) => boolean;

    action?: (
        context: OrderContext
    ) => Promise<void>;
}

Then:

const transitions = {
    [OrderState.PENDING_PAYMENT]: {
        [OrderEvent.PAYMENT_COMPLETED]: {
            target: OrderState.PAID
        },

        [OrderEvent.CANCEL]: {
            target: OrderState.CANCELLED
        }
    },

    [OrderState.PAID]: {
        [OrderEvent.START_PROCESSING]: {
            target: OrderState.PROCESSING
        }
    },

    [OrderState.PROCESSING]: {
        [OrderEvent.SHIP]: {
            target: OrderState.SHIPPED
        },

        [OrderEvent.FAILURE]: {
            target: OrderState.FAILED
        }
    },

    [OrderState.SHIPPED]: {
        [OrderEvent.DELIVER]: {
            target: OrderState.DELIVERED
        }
    },

    [OrderState.FAILED]: {
        [OrderEvent.RETRY]: {
            target: OrderState.PROCESSING
        }
    }
};

FSM Engine

Now we can create a generic engine.

class OrderStateMachine {

    constructor(
        private state: OrderState,
        private context: OrderContext
    ) {}

    getState(): OrderState {
        return this.state;
    }

    async dispatch(
        event: OrderEvent
    ): Promise<OrderState> {

        const stateTransitions =
            transitions[this.state];

        const transition =
            stateTransitions?.[event];

        if (!transition) {
            throw new Error(
                `Invalid transition: ${this.state} + ${event}`
            );
        }

        if (
            transition.guard &&
            !transition.guard(this.context)
        ) {
            throw new Error(
                "Transition guard failed"
            );
        }

        if (transition.action) {
            await transition.action(
                this.context
            );
        }

        this.state = transition.target;

        return this.state;
    }
}

Persistence

A production FSM should not rely only on memory.

We can persist the state in PostgreSQL.

Example database structure:

CREATE TABLE orders (
    id UUID PRIMARY KEY,
    customer_id UUID NOT NULL,
    amount NUMERIC NOT NULL,
    state VARCHAR(50) NOT NULL,
    version INTEGER NOT NULL DEFAULT 0,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

The important fields are:

state
version

The version helps with optimistic concurrency.

Optimistic Concurrency

Imagine two requests arrive simultaneously:

Request A: PAY
Request B: CANCEL

Both read:

state = PENDING_PAYMENT
version = 10

If both update the row without protection, we may get inconsistent behavior.

Optimistic concurrency solves this.

Example:

UPDATE orders
SET
    state = $1,
    version = version + 1
WHERE
    id = $2
    AND version = $3;

If zero rows are updated, someone else modified the order.

Then we reject the operation.

Idempotency

Distributed systems can deliver the same event more than once.

For example:

PAYMENT_COMPLETED
PAYMENT_COMPLETED

If the first event changes:

PENDING_PAYMENT → PAID

the second event should not perform the payment transition again.

We can store processed event IDs.

CREATE TABLE processed_events (
    event_id UUID PRIMARY KEY,
    processed_at TIMESTAMP NOT NULL
);

Before processing:

Does event_id exist?

YES → Ignore
NO  → Process

This is a common production pattern.

Retry / Failure States

Failures are normal in distributed systems.

For example:

PROCESSING
    |
    | FAILURE
    v
FAILED
    |
    | RETRY
    v
PROCESSING

We can store:

retryCount

Then:

if (context.retryCount >= 3) {
    transitionTo("PERMANENT_FAILURE");
}

A more complete model might be:

PROCESSING
    |
    | ERROR
    v
RETRYING
    |
    +---- RETRY ----> PROCESSING
    |
    +---- MAX_RETRIES ---> FAILED

Exponential Backoff

Retries should usually not happen immediately.

A common strategy is exponential backoff:

Attempt 1 → 1 second
Attempt 2 → 2 seconds
Attempt 3 → 4 seconds
Attempt 4 → 8 seconds

Formula:

delay = baseDelay × 2^retryCount

With jitter:

delay =
    baseDelay × 2^retryCount
    + randomJitter

This helps prevent many workers from retrying simultaneously.

Express API

We can expose an endpoint:

POST /orders/:id/events

Request:

{
    "event": "PAYMENT_COMPLETED"
}

Controller:

router.post(
    "/orders/:id/events",
    async (req, res) => {

        const { id } = req.params;
        const { event } = req.body;

        const order =
            await orderRepository.findById(id);

        if (!order) {
            return res
                .status(404)
                .json({
                    message: "Order not found"
                });
        }

        const machine =
            new OrderStateMachine(
                order.state,
                order.context
            );

        const newState =
            await machine.dispatch(event);

        await orderRepository.updateState(
            id,
            newState
        );

        return res.json({
            orderId: id,
            state: newState
        });
    }
);

Better Production Design

However, in a real production application, we should avoid directly coupling:

Controller
   ↓
FSM
   ↓
Database

A better architecture is:

Controller
    ↓
Application Service
    ↓
Domain FSM
    ↓
Repository
    ↓
Database

For example:

HTTP Controller
      |
      v
OrderApplicationService
      |
      v
OrderStateMachine
      |
      v
OrderRepository
      |
      v
PostgreSQL

This follows separation of concerns.

Domain Layer

The FSM belongs to the domain layer because it contains business rules.

Example:

class Order {

    constructor(
        public readonly id: string,
        private state: OrderState,
        private context: OrderContext
    ) {}

    async apply(
        event: OrderEvent
    ) {

        const machine =
            new OrderStateMachine(
                this.state,
                this.context
            );

        this.state =
            await machine.dispatch(event);
    }

    getState() {
        return this.state;
    }
}

The domain should not know about:

Express
HTTP
Redis
PostgreSQL

This keeps business logic independent.

Application Layer

The Application Service coordinates operations.

class OrderApplicationService {

    constructor(
        private readonly repository:
            OrderRepository
    ) {}

    async handleEvent(
        orderId: string,
        event: OrderEvent
    ) {

        const order =
            await this.repository
                .findById(orderId);

        if (!order) {
            throw new Error(
                "Order not found"
            );
        }

        await order.apply(event);

        await this.repository.save(order);

        return order;
    }
}

Repository Layer

The repository handles persistence.

interface OrderRepository {

    findById(
        id: string
    ): Promise<Order | null>;

    save(
        order: Order
    ): Promise<void>;
}

The domain remains independent from PostgreSQL.

Event Publishing

After a successful transition:

PENDING_PAYMENT
       |
       | PAYMENT_COMPLETED
       v
      PAID

we may publish:

OrderPaid

Other services can subscribe.

Order Service
     |
     | OrderPaid
     v
Message Broker
     |
     +----> Notification
     |
     +----> Analytics
     |
     +----> Shipping

Transactional Consistency

A critical production problem is:

Update Database
      +
Publish Event

What happens if:

Database update succeeds
Event publishing fails

Now the order is:

PAID

but other services never receive:

OrderPaid

A common solution is the Transactional Outbox Pattern.

Transactional Outbox

Instead of immediately publishing the event:

Database
   |
   +-- Update Order
   |
   +-- Insert Outbox Event

Both happen inside the same database transaction.

Example:

BEGIN;

UPDATE orders
SET state = 'PAID'
WHERE id = $1;

INSERT INTO outbox_events (
    id,
    type,
    payload
)
VALUES (
    $2,
    'OrderPaid',
    $3
);

COMMIT;

Then a background worker reads the outbox:

Outbox
   |
   v
Publisher
   |
   v
Message Broker

This significantly improves reliability.

Observability

A production FSM should be observable.

Important metrics include:

state_transition_total
state_transition_failure_total
invalid_transition_total
fsm_processing_duration
retry_total

Logs should include:

{
    "orderId": "123",
    "from": "PENDING_PAYMENT",
    "event": "PAYMENT_COMPLETED",
    "to": "PAID"
}

This makes debugging much easier.

State Transition Logging

Every transition should ideally be traceable.

Order 123

PENDING_PAYMENT
      |
      | PAYMENT_COMPLETED
      v
PAID
      |
      | START_PROCESSING
      v
PROCESSING
      |
      | SHIP
      v
SHIPPED

A transition log can contain:

orderId
previousState
event
newState
timestamp
actor
correlationId

Testing an FSM

One of the biggest advantages of FSMs is testability.

We can test transitions independently.

Example:

describe(
    "Order State Machine",
    () => {

        it(
            "should transition from pending to paid",
            async () => {

                const machine =
                    new OrderStateMachine(
                        OrderState.PENDING_PAYMENT,
                        context
                    );

                await machine.dispatch(
                    OrderEvent.PAYMENT_COMPLETED
                );

                expect(
                    machine.getState()
                ).toBe(OrderState.PAID);
            }
        );
    }
);

Testing Invalid Transitions

We should also test invalid operations.

it(
    "should reject shipping before payment",
    async () => {

        const machine =
            new OrderStateMachine(
                OrderState.PENDING_PAYMENT,
                context
            );

        await expect(
            machine.dispatch(
                OrderEvent.SHIP
            )
        ).rejects.toThrow();
    }
);

This is extremely important.

A good FSM test suite should test:

Valid transitions
Invalid transitions
Guards
Actions
Retries
Concurrency
Persistence
Recovery

Testing State Invariants

Suppose:

SHIPPED

requires:

trackingNumber

Test:

expect(() =>
    createOrder({
        state: OrderState.SHIPPED,
        trackingNumber: undefined
    })
).toThrow();

This ensures invalid states cannot exist.

Property-Based Testing

FSMs are also excellent candidates for property-based testing.

We can define properties such as:

The machine must never reach an undefined state.

Or:

DELIVERED must never transition back to PENDING_PAYMENT.

Or:

CANCELLED orders cannot become SHIPPED.

This allows automated generation of event sequences.

Example sequence:

PAY
SHIP
DELIVER
CANCEL
PAY
SHIP

The test verifies that no invalid state is produced.

Concurrency Testing

Production systems must test concurrent requests.

Example:

Request A:
PAYMENT_COMPLETED

Request B:
CANCEL

Both arrive simultaneously.

The system must guarantee that only one valid transition succeeds.

Optimistic locking can enforce this.

Version = 10

Request A:
10 → 11

Request B:
10 → FAIL

Request B receives:

CONCURRENT_MODIFICATION

and can retry after reloading the latest state.

Complete Production Flow

Let's put everything together.

                   HTTP Request
                        |
                        v
                Express Controller
                        |
                        v
             Application Service
                        |
                        v
                  Load Order
                        |
                        v
                Current State
                        |
                        v
                  FSM Engine
                        |
              +---------+---------+
              |                   |
           Guard                Invalid
              |                   |
              v                   v
        Transition            Reject Event
              |
              v
          New State
              |
              v
       Database Transaction
              |
        +-----+------+
        |            |
        v            v
   Update Order   Outbox Event
        |            |
        +-----+------+
              |
              v
            Commit
              |
              v
       Background Publisher
              |
              v
        Message Broker
              |
       +------+------+
       |             |
       v             v
 Notification     Shipping

This architecture demonstrates why State Machines are useful beyond simple examples.

Recommended Project Structure

A production Node.js + TypeScript project could look like:

src/
│
├── domain/
│   └── order/
│       ├── order.entity.ts
│       ├── order-state.ts
│       ├── order-event.ts
│       ├── order-state-machine.ts
│       └── order.errors.ts
│
├── application/
│   └── order/
│       ├── create-order.service.ts
│       ├── process-order-event.service.ts
│       └── cancel-order.service.ts
│
├── infrastructure/
│   ├── database/
│   │   ├── postgres.ts
│   │   └── order.repository.ts
│   │
│   ├── messaging/
│   │   └── event-publisher.ts
│   │
│   └── cache/
│       └── redis.ts
│
├── interfaces/
│   └── http/
│       ├── controllers/
│       ├── routes/
│       └── middleware/
│
├── workers/
│   └── outbox.worker.ts
│
├── config/
│   └── environment.ts
│
└── server.ts

This separates:

Domain
Application
Infrastructure
Interfaces
Workers
Configuration

FSM Design Principles

When designing a State Machine, follow these principles.

1. Keep States Meaningful

A state should represent a meaningful business condition.

Bad:

STEP_1
STEP_2
STEP_3

Better:

PENDING_PAYMENT
PAID
PROCESSING
SHIPPED
DELIVERED

2. Keep Events Explicit

Avoid vague events such as:

UPDATE
CHANGE
PROCESS

Prefer:

PAYMENT_COMPLETED
ORDER_SHIPPED
DELIVERY_CONFIRMED
PAYMENT_FAILED

Explicit events make systems easier to understand.

3. Make Invalid Transitions Impossible

Do not allow:

DELIVERED → PAID

unless the domain explicitly requires it.

4. Separate State from Context

State:

PAID

Context:

{
    orderId,
    customerId,
    amount,
    paymentId
}

This prevents the state from becoming a giant data structure.

5. Keep Side Effects Controlled

The transition logic should be predictable.

Instead of mixing everything:

transition() {
    updateDatabase();
    sendEmail();
    callStripe();
    publishKafkaMessage();
    updateRedis();
}

prefer:

FSM
 ↓
Domain Event
 ↓
Application / Infrastructure

This gives better separation.

Common FSM Mistakes

Mistake 1 — Using Too Many Boolean Flags

Instead of:

isLoading
isSuccess
isError
isCancelled

use:

IDLE
LOADING
SUCCESS
ERROR
CANCELLED

One state is often better than many independent booleans.

Mistake 2 — Allowing Impossible States

For example:

isLoading = true
isSuccess = true

An FSM can eliminate these combinations.

Mistake 3 — Putting Everything Into One FSM

Don't create:

OrderPaymentShippingInventoryNotificationFSM

Split independent concerns.

Order FSM
Payment FSM
Shipping FSM
Notification FSM

Mistake 4 — Ignoring Concurrency

An FSM in memory may be correct locally but incorrect in a distributed system.

Always consider:

Concurrent events
Duplicate events
Out-of-order events
Retries
Persistence

Mistake 5 — Treating Persistence as an Afterthought

If state matters, persist it.

For critical workflows:

state
version
transition history
event ID
timestamp

can be extremely valuable.

FSM vs State Pattern

FSM and the State Pattern are related but not identical.

A State Machine focuses on:

States
Events
Transitions
Rules

The State Pattern is an Object-Oriented design pattern where behavior is delegated to state objects.

Example:

Order
  |
  +-- PendingState
  +-- PaidState
  +-- ShippedState

The State Pattern can be used to implement an FSM, but an FSM does not have to use the State Pattern.

FSM vs Workflow Engine

An FSM is usually focused on:

States + Transitions

A Workflow Engine often provides much more:

Long-running workflows
Timers
Retries
Persistence
Distributed execution
Compensation
Human approval
Recovery

Examples of workflow-oriented systems include platforms such as Temporal.

FSMs can be part of a workflow engine, but they are conceptually smaller.

FSM vs Event-Driven Architecture

These concepts are also different.

FSM:

State + Event → New State

Event-driven architecture:

Event → Subscribers

They can work together.

For example:

PaymentCompleted
       |
       v
Order FSM
       |
       v
PAID
       |
       v
OrderPaid
       |
       +----> Notification
       +----> Shipping
       +----> Analytics

FSM Mental Model

A very useful mental model is:

STATE
  +
EVENT
  +
GUARD
  |
  v
TRANSITION
  |
  +---- ACTION
  |
  v
NEW STATE

Or even more simply:

Where am I?
     +
What happened?
     +
Am I allowed?
     ↓
Where do I go?
     +
What should I do?

The Most Important Formula

The core of a State Machine can be summarized as:

δ(State, Event) → State

For a more practical application:

Transition =
    Current State
    +
    Event
    +
    Optional Guard
    →
    Next State
    +
    Optional Action

A Complete Example

Consider an online order:

                    PAYMENT_COMPLETED
       +--------------------------------------+
       |                                      |
       v                                      |
+------------------+                    +----------+
| PENDING_PAYMENT  | -----------------> |   PAID   |
+------------------+                    +----------+
       |                                      |
       | CANCEL                               | PROCESS
       v                                      v
+-------------+                         +-------------+
|  CANCELLED  |                         | PROCESSING  |
+-------------+                         +-------------+
                                              |
                                              | SHIP
                                              v
                                         +---------+
                                         | SHIPPED |
                                         +---------+
                                              |
                                              | DELIVER
                                              v
                                         +-----------+
                                         | DELIVERED |
                                         +-----------+

The machine guarantees that:

PENDING_PAYMENT
    → PAID
    → PROCESSING
    → SHIPPED
    → DELIVERED

is valid.

But:

PENDING_PAYMENT
    → SHIPPED

is invalid.

And:

DELIVERED
    → PENDING_PAYMENT

is also invalid.

This is the core value of State Machines:

They make valid behavior explicit and invalid behavior enforceable.

When Should You Use an FSM?

FSMs are especially useful when:

A system has a lifecycle
There are explicit states
Transitions depend on events
Invalid transitions matter
Business rules are complex
The workflow needs to be visualized
You need strong testability
You need predictable behavior

Examples:

Authentication
Payments
Orders
Checkout
Jobs
Retries
Connections
UI workflows
Games
Embedded systems

When Should You Avoid an FSM?

Not every problem needs one.

If the logic is simply:

const result = calculatePrice(input);

there is probably no reason to introduce an FSM.

FSMs are useful when there is a meaningful lifecycle.

If there are no meaningful states or transitions, an FSM may add unnecessary complexity.

Final Production Checklist

Before deploying an FSM-based system, ask:

[ ] Are all states explicitly defined?
[ ] Are all events explicitly defined?
[ ] Is there a clear initial state?
[ ] Are valid transitions documented?
[ ] Are invalid transitions rejected?
[ ] Are guards tested?
[ ] Are actions controlled?
[ ] Are invariants enforced?
[ ] Is state persisted when necessary?
[ ] Is concurrency handled?
[ ] Is idempotency implemented?
[ ] Are duplicate events handled?
[ ] Are retries controlled?
[ ] Is exponential backoff used?
[ ] Is transition history observable?
[ ] Are metrics available?
[ ] Are logs structured?
[ ] Are transitions unit tested?
[ ] Are invalid transitions tested?
[ ] Is state explosion controlled?
[ ] Are independent workflows separated?

Conclusion

Finite State Machines are much more than a theoretical computer science concept.

They provide a practical way to model systems that evolve through well-defined states.

The fundamental model is simple:

State
 +
Event
 ↓
Transition
 ↓
New State

But this simple abstraction can scale into powerful architectural patterns.

We can use:

Guards
Actions
Entry / Exit Actions
Hierarchical States
Nested States
Parallel States
History
Event Queues
Persistence
Concurrency Control
Idempotency
Retries
Event Sourcing
CQRS
Event-Driven Architecture
Microservices

In modern backend systems, State Machines are particularly valuable for workflows such as:

Orders
Payments
Authentication
Jobs
Retries
Shipping
Subscriptions
WebSocket Connections

The most important lesson is not how to write an FSM.

It is how to think in terms of explicit states, explicit events, explicit transitions, and explicit business rules.

Instead of writing code that implicitly describes what the system can do, a State Machine lets us explicitly define:

What states are possible?
What events can occur?
Which transitions are legal?
Which transitions are invalid?
What conditions must be satisfied?
What side effects should happen?
How should the system recover from failure?

That is why State Machines remain useful from simple applications to production distributed systems.

At the simplest level:

State + Event → Next State

At the production level:

Event
  ↓
Validation
  ↓
Current State
  ↓
Guard
  ↓
FSM Transition
  ↓
New State
  ↓
Persistence
  ↓
Outbox Event
  ↓
Message Broker
  ↓
Distributed Consumers
  ↓
Observability

Once you start seeing software systems as state transitions, many complex workflows become easier to design, reason about, test, and maintain.

A well-designed State Machine does not merely describe what a system does — it defines what the system is allowed to do.

Functional Programming vs Object-Oriented Programming in JavaScript

Abanoub Kerols — Thu, 06 Aug 2026 07:47:32 +0000

A Practical Guide to FP, OOP, Prototypes, Composition, Currying, Immutability, and Encapsulation

Modern JavaScript supports multiple programming paradigms. Two of the most important are:

Object-Oriented Programming (OOP)
Functional Programming (FP)

JavaScript is particularly interesting because it is a multi-paradigm language. You can build applications using classes and inheritance, functional composition and higher-order functions, or combine both approaches.

Understanding these paradigms is more important than simply knowing their syntax. The real skill is knowing how the underlying concepts affect architecture, state management, testability, reusability, and maintainability.

This article explores the major concepts behind both paradigms and shows how they work internally in JavaScript.

Programming Paradigms
Functional Programming
Object-Oriented Programming
Abstract Classes and Inheritance
Prototypes and Constructors
Composition Over Inheritance
Functional Composition
Factory Functions
Currying
Partial Application
Higher-Order Functions
Lambda Functions
Recursive Functions
Pure Functions
Immutable vs Mutable State
Private Properties and Methods
FP vs OOP
Using FP and OOP Together
Real-World Architecture Example
Best Practices
Conclusion

1. Programming Paradigms

A programming paradigm is a way of thinking about how software should be structured.

Instead of asking:

"What syntax should I use?"

we should ask:

"How should I model the problem?"

Two major approaches are:

Programming
│
├── Imperative
│   ├── Procedural
│   └── Object-Oriented
│
└── Declarative
    └── Functional

Consider a simple requirement:

Calculate the total price of products.

An imperative approach might say:

let total = 0;

for (const product of products) {
    total += product.price;
}

A functional approach describes the transformation:

const total = products.reduce(
    (sum, product) => sum + product.price,
    0
);

The difference is not just syntax.

It is about how we reason about the program.

2. Functional Programming

Functional Programming treats computation primarily as the evaluation of functions.

The central idea is:

Build programs by composing small functions that transform data.

For example:

const addTax = price => price * 1.14;

const addShipping = price => price + 100;

const calculateOrderTotal = price =>
    addShipping(addTax(price));

console.log(calculateOrderTotal(1000));

Each function performs one transformation.

Conceptually:

price
  ↓
addTax
  ↓
addShipping
  ↓
result

Functional programming emphasizes:

Pure functions
Immutability
Function composition
Higher-order functions
Referential transparency
Declarative programming
Avoiding shared mutable state

3. Object-Oriented Programming

Object-Oriented Programming organizes software around objects.

An object combines:

State + Behavior

For example:

class BankAccount {
    constructor(balance) {
        this.balance = balance;
    }

    deposit(amount) {
        this.balance += amount;
    }

    withdraw(amount) {
        if (amount > this.balance) {
            throw new Error("Insufficient funds");
        }

        this.balance -= amount;
    }
}

Usage:

const account = new BankAccount(1000);

account.deposit(500);
account.withdraw(200);

console.log(account.balance);

The object owns both:

State
  ↓
balance

Behavior
  ↓
deposit()
withdraw()

OOP commonly uses:

Encapsulation
Abstraction
Inheritance
Polymorphism
Composition

4. Abstract Classes and Inheritance

Abstraction means exposing what an object can do while hiding implementation details.

For example:

class PaymentProcessor {
    processPayment(amount) {
        throw new Error("processPayment() must be implemented");
    }
}

Then:

class StripePayment extends PaymentProcessor {
    processPayment(amount) {
        console.log(`Processing ${amount} using Stripe`);
    }
}

And:

class PayPalPayment extends PaymentProcessor {
    processPayment(amount) {
        console.log(`Processing ${amount} using PayPal`);
    }
}

Now we can work with the abstraction:

function checkout(processor, amount) {
    processor.processPayment(amount);
}

Usage:

checkout(new StripePayment(), 500);
checkout(new PayPalPayment(), 500);

This demonstrates polymorphism.

The caller doesn't need to know the concrete implementation.

Important JavaScript Difference

Unlike Java or C#, JavaScript does not have a traditional abstract class keyword.

We usually simulate abstraction using:

class PaymentProcessor {
    processPayment() {
        throw new Error("Not implemented");
    }
}

Or we can use TypeScript:

abstract class PaymentProcessor {
    abstract processPayment(amount: number): void;
}

class StripePayment extends PaymentProcessor {
    processPayment(amount: number) {
        console.log(amount);
    }
}

5. Prototypes and Constructors

JavaScript is fundamentally prototype-based.

Classes are largely syntactic sugar over JavaScript's prototype system.

Consider:

function User(name) {
    this.name = name;
}

User.prototype.sayHello = function () {
    console.log(`Hello ${this.name}`);
};

Now:

const user1 = new User("John");
const user2 = new User("Alice");

Both objects can access:

user1.sayHello();
user2.sayHello();

But the method does not need to be copied into every object.

Instead:

user1
   │
   ▼
User.prototype
   │
   └── sayHello()

user2
   │
   ▼
User.prototype
   │
   └── sayHello()

This is the prototype chain.

What Does `new` Do?

When we write:

const user = new User("John");

JavaScript roughly performs these steps:

1. Create a new object
2. Link object to User.prototype
3. Execute User with `this`
4. Return the object

Conceptually:

const user = Object.create(User.prototype);

User.call(user, "John");

This is not a complete specification-level implementation, but it provides the right mental model.

6. Composition Over Inheritance

Inheritance can become problematic when hierarchies become deep.

Imagine:

Animal
  ↓
Mammal
  ↓
FlyingMammal
  ↓
FlyingSwimmingMammal

As requirements grow, the hierarchy becomes difficult to maintain.

Composition takes another approach.

Instead of asking:

"What is this object?"

we ask:

"What capabilities does this object have?"

For example:

const canWalk = state => ({
    walk() {
        console.log(`${state.name} is walking`);
    }
});

const canFly = state => ({
    fly() {
        console.log(`${state.name} is flying`);
    }
});

const canSwim = state => ({
    swim() {
        console.log(`${state.name} is swimming`);
    }
});

Now:

const bird = {
    name: "Eagle",
    ...canWalk({ name: "Eagle" }),
    ...canFly({ name: "Eagle" })
};

And:

const duck = {
    name: "Duck",
    ...canWalk({ name: "Duck" }),
    ...canFly({ name: "Duck" }),
    ...canSwim({ name: "Duck" })
};

Instead of building a large inheritance tree, we compose capabilities.

7. Functional Composition

Functional composition means combining functions to create a new function.

Suppose we have:

const double = x => x * 2;

const square = x => x * x;

We can compose them:

const doubleThenSquare = x =>
    square(double(x));

Then:

doubleThenSquare(3);

Execution:

3
 ↓
double
 ↓
6
 ↓
square
 ↓
36

Building a `compose` Function

We can generalize the concept:

const compose = (...functions) =>
    value =>
        functions.reduceRight(
            (result, fn) => fn(result),
            value
        );

Now:

const doubleThenSquare = compose(
    square,
    double
);

console.log(doubleThenSquare(3));

Result:

We can also create pipe, which executes from left to right:

const pipe = (...functions) =>
    value =>
        functions.reduce(
            (result, fn) => fn(result),
            value
        );

Then:

const processPrice = pipe(
    price => price * 1.14,
    price => price + 100,
    price => Math.round(price)
);

Usage:

processPrice(1000);

This style is very common in functional JavaScript.

8. Factory Functions

A factory function is a function that creates objects.

Instead of:

class User {
    constructor(name) {
        this.name = name;
    }

    greet() {
        return `Hello ${this.name}`;
    }
}

we can use:

function createUser(name) {
    return {
        name,

        greet() {
            return `Hello ${this.name}`;
        }
    };
}

Usage:

const user = createUser("John");

console.log(user.greet());

Factory functions are particularly useful when combined with composition.

Factory + Composition

const createUser = name => ({
    name
});

const withAuthentication = user => ({
    ...user,

    login() {
        console.log(`${user.name} logged in`);
    }
});

const withPermissions = user => ({
    ...user,

    hasPermission(permission) {
        return permission === "admin";
    }
});

Now:

const admin = withPermissions(
    withAuthentication(
        createUser("John")
    )
);

This gives us a composable object.

9. Currying

Currying transforms a function that takes multiple arguments into a sequence of functions that each take one argument.

Normal function:

const add = (a, b) => a + b;

Curried version:

const add = a => b => a + b;

Usage:

add(10)(20);

Result:

Why Is Currying Useful?

Because it allows us to specialize functions.

For example:

const multiply = a => b => a * b;

const double = multiply(2);
const triple = multiply(3);

Now:

double(10); // 20
triple(10); // 30

We created specialized functions from a general function.

10. Partial Application

Currying and partial application are related but not identical.

Partial application means:

Fix some arguments now and provide the rest later.

Consider:

const createUser = (role, name, age) => ({
    role,
    name,
    age
});

We can specialize the role:

const createAdmin = (name, age) =>
    createUser("admin", name, age);

Now:

createAdmin("John", 30);

Conceptually:

createUser
   │
   ├── role = admin
   │
   ▼
createAdmin

Partial application is useful for creating reusable domain-specific functions.

11. Higher-Order Functions

A higher-order function is a function that:

Receives another function as an argument
Returns a function
Or both

For example:

function executeOperation(a, b, operation) {
    return operation(a, b);
}

Usage:

executeOperation(10, 20, (a, b) => a + b);

Result:

JavaScript's array methods are excellent examples:

map()
filter()
reduce()
some()
every()
find()

For example:

const users = [
    { name: "John", active: true },
    { name: "Alice", active: false },
    { name: "Bob", active: true }
];

const activeUsers = users.filter(
    user => user.active
);

filter is a higher-order function because it receives a function.

12. Lambda Functions

In JavaScript, lambda functions are generally represented by arrow functions.

Example:

const square = x => x * x;

Compared to:

function square(x) {
    return x * x;
}

Arrow functions provide concise syntax.

They are especially useful for callbacks:

users.map(user => user.name);

Important: Arrow Functions and `this`

Arrow functions do not create their own this.

Example:

const user = {
    name: "John",

    regular() {
        console.log(this.name);
    },

    arrow: () => {
        console.log(this.name);
    }
};

The regular method receives this based on how it is called.

The arrow function captures this lexically from the surrounding scope.

This difference becomes extremely important in JavaScript applications.

13. Recursive Functions

A recursive function calls itself.

The classic example is factorial:

function factorial(n) {
    if (n === 0) {
        return 1;
    }

    return n * factorial(n - 1);
}

Execution:

factorial(4)

4 × factorial(3)

4 × 3 × factorial(2)

4 × 3 × 2 × factorial(1)

4 × 3 × 2 × 1

24

The critical part is the base case:

if (n === 0) {
    return 1;
}

Without a base case, recursion can continue indefinitely until the call stack is exhausted.

Recursive Tree Traversal

Recursion becomes especially useful when working with hierarchical data.

const tree = {
    value: 1,

    children: [
        {
            value: 2,
            children: []
        },
        {
            value: 3,
            children: [
                {
                    value: 4,
                    children: []
                }
            ]
        }
    ]
};

We can traverse it recursively:

function traverse(node) {
    console.log(node.value);

    for (const child of node.children) {
        traverse(child);
    }
}

This pattern appears in:

File systems
DOM trees
ASTs
Organizational structures
Dependency graphs
Nested menus

14. Pure Functions

A pure function has two important properties:

1. Same input → same output

const add = (a, b) => a + b;

For:

add(2, 3);

the result will always be:

2. No side effects

A pure function doesn't modify external state.

Impure:

let total = 0;

function add(amount) {
    total += amount;
}

The function changes external state.

Pure:

function add(total, amount) {
    return total + amount;
}

Now the state is explicit.

Why Pure Functions Matter

Pure functions are easier to:

Test
Debug
Cache
Reason about
Parallelize
Reuse

For example:

expect(add(10, 20)).toBe(30);

There is no dependency on external state.

15. Immutable vs Mutable State

Mutable state means changing existing data.

const user = {
    name: "John",
    age: 30
};

user.age = 31;

The same object was modified.

With immutable updates:

const updatedUser = {
    ...user,
    age: 31
};

Now:

user
 ↓
original object

updatedUser
 ↓
new object

The original remains unchanged.

Why Immutability Matters

Immutability makes state transitions easier to reason about.

Consider:

const state1 = {
    count: 0
};

const state2 = {
    ...state1,
    count: state1.count + 1
};

const state3 = {
    ...state2,
    count: state2.count + 1
};

We now have:

state1 → state2 → state3

This idea is fundamental to state-management systems.

For example, reducer-style state updates:

function reducer(state, action) {
    switch (action.type) {
        case "INCREMENT":
            return {
                ...state,
                count: state.count + 1
            };

        default:
            return state;
    }
}

Instead of modifying state directly, the reducer returns a new state.

Mutable State Isn't Always Bad

It is important not to turn immutability into a dogma.

Mutation can sometimes be more efficient.

For example:

const array = [];

for (let i = 0; i < 1_000_000; i++) {
    array.push(i);
}

Repeatedly creating new arrays could introduce unnecessary allocations.

The important question is:

Where is mutation allowed, and who owns it?

A practical architecture may use:

Immutable at boundaries
        ↓
Controlled mutation internally
        ↓
Immutable result

This gives you predictable APIs without forcing every internal operation to allocate new objects.

16. Private Properties and Methods

Encapsulation means hiding internal implementation details.

Modern JavaScript supports private class fields using #.

class BankAccount {
    #balance;

    constructor(balance) {
        this.#balance = balance;
    }

    deposit(amount) {
        this.#balance += amount;
    }

    getBalance() {
        return this.#balance;
    }
}

Now:

const account = new BankAccount(1000);

account.deposit(500);

console.log(account.getBalance());

But:

account.#balance;

is invalid.

The property is truly private.

Private Methods

JavaScript also supports private methods:

class UserService {
    #validate(user) {
        if (!user.email) {
            throw new Error("Email is required");
        }
    }

    createUser(user) {
        this.#validate(user);

        console.log("User created");
    }
}

The caller can use:

service.createUser(user);

but cannot directly call:

service.#validate(user);

17. FP vs OOP

Let's compare the mental models.

Concept	Functional Programming	Object-Oriented Programming
Main abstraction	Functions	Objects
Primary focus	Data transformations	State + behavior
State	Prefer immutable	Often encapsulated/mutable
Reuse	Composition	Inheritance/composition
Side effects	Minimized	Encapsulated
Polymorphism	Higher-order functions / protocols	Inheritance / interfaces
Data flow	Explicit	Often object-centered
Testing	Pure functions are easy	Objects require state setup
Best for	Transformations	Stateful domains

But this table should not lead to:

"FP is better."

or:

"OOP is better."

The better question is:

"Which model fits this problem?"

18. Using FP and OOP Together

Real-world JavaScript applications frequently combine both paradigms.

For example:

class UserService {
    constructor(repository) {
        this.repository = repository;
    }

    async getActiveUsers() {
        const users = await this.repository.findAll();

        return users
            .filter(user => user.active)
            .map(user => ({
                id: user.id,
                name: user.name
            }));
    }
}

The service uses OOP:

class UserService

and functional programming internally:

.filter(...)
.map(...)

This is often a very practical approach.

19. Real-World Architecture Example

Consider an e-commerce system.

We might have:

OrderService
     │
     ├── Repository
     │
     ├── PaymentService
     │
     └── NotificationService

OOP can model long-lived services:

class OrderService {
    constructor(orderRepository, paymentService) {
        this.orderRepository = orderRepository;
        this.paymentService = paymentService;
    }

    async createOrder(order) {
        // orchestration
    }
}

FP can handle transformations:

const calculateSubtotal = items =>
    items.reduce(
        (total, item) =>
            total + item.price * item.quantity,
        0
    );

Tax:

const calculateTax = rate => subtotal =>
    subtotal * rate;

Discount:

const applyDiscount = discount => total =>
    total - discount;

Then compose the calculation:

const calculateTotal = (items, taxRate, discount) => {
    const subtotal = calculateSubtotal(items);

    const tax = calculateTax(taxRate)(subtotal);

    return applyDiscount(discount)(
        subtotal + tax
    );
};

The architecture becomes:

        OOP
         │
         ▼
   Application Services
         │
         ▼
       FP
         │
         ▼
 Pure Domain Logic
         │
         ▼
       Data

This separation can be extremely powerful.

20. A More Advanced Example

Suppose we need to process orders.

Raw data:

const orders = [
    {
        id: 1,
        status: "completed",
        total: 500
    },
    {
        id: 2,
        status: "pending",
        total: 300
    },
    {
        id: 3,
        status: "completed",
        total: 700
    }
];

We can build small pure functions:

const isCompleted = order =>
    order.status === "completed";

const getTotal = order =>
    order.total;

const sum = (a, b) =>
    a + b;

Then:

const revenue = orders
    .filter(isCompleted)
    .map(getTotal)
    .reduce(sum, 0);

Result:

Each function has one responsibility.

This makes the code easy to test:

isCompleted(orders[0]); // true

getTotal(orders[0]); // 500

sum(500, 700); // 1200

21. A Practical Decision Framework

Instead of choosing FP or OOP based on preference, consider the problem.

Use Functional Programming heavily when:

Data transformation is the main problem.
You have pipelines of operations.
You need predictable business rules.
You want highly testable logic.
You want to minimize shared state.

Examples:

Data processing
Validation
Calculations
Reducers
Transformations
Parsing
Mapping
Filtering
Aggregation

Use OOP heavily when:

You have long-lived entities.
Objects own state.
You need encapsulation.
You have complex domain behavior.
You need dependency injection.
You are modeling external resources/services.

Examples:

PaymentService
DatabaseRepository
FileStorage
ConnectionPool
Order
UserSession
Cache

Use Composition when:

You have reusable capabilities.

Instead of:

BaseUser
  ↓
AdminUser
  ↓
SuperAdminUser

consider:

User
 + Authentication
 + Authorization
 + Logging
 + Auditing

22. The Deeper Idea: Data vs Behavior

One of the biggest philosophical differences between FP and OOP is how they organize behavior.

OOP tends to ask:

"Who owns this behavior?"

For example:

order.calculateTotal();

The behavior belongs to order.

FP tends to ask:

"What transformation should happen to this data?"

For example:

calculateTotal(order);

Neither approach is universally correct.

They represent two different ways of modeling the same problem.

23. Referential Transparency

A function is referentially transparent when we can replace the function call with its result without changing program behavior.

For example:

const square = x => x * x;

Then:

square(5)

can always be replaced with:

Consider:

const result = square(5) + square(5);

We can reason about it as:

const result = 25 + 25;

This property makes functional code easier to reason about.

Compare that with:

let counter = 0;

function increment() {
    return ++counter;
}

Calling:

increment();

cannot be replaced with a fixed value because the result depends on external state.

24. Closures and Functional Programming

Closures are another fundamental JavaScript feature.

Consider:

function createCounter() {
    let count = 0;

    return function () {
        count++;

        return count;
    };
}

Usage:

const counter = createCounter();

counter(); // 1
counter(); // 2
counter(); // 3

The returned function remembers:

count

even after createCounter() has finished.

This creates private state without using a class.

25. Factory Functions + Closures

This allows us to build encapsulated objects using FP techniques.

function createBankAccount(initialBalance) {
    let balance = initialBalance;

    return {
        deposit(amount) {
            balance += amount;
        },

        withdraw(amount) {
            if (amount > balance) {
                throw new Error("Insufficient funds");
            }

            balance -= amount;
        },

        getBalance() {
            return balance;
        }
    };
}

Now:

const account = createBankAccount(1000);

account.deposit(500);

console.log(account.getBalance());

But:

account.balance;

is:

undefined

because balance exists only inside the closure.

This is an alternative form of encapsulation.

26. OOP Encapsulation vs Closure Encapsulation

OOP:

class BankAccount {
    #balance;

    constructor(balance) {
        this.#balance = balance;
    }
}

Functional:

function createBankAccount(balance) {
    return {
        getBalance() {
            return balance;
        }
    };
}

Both can provide encapsulation.

The difference is the underlying model.

OOP
Object
 ├── State
 └── Methods

FP
Closure
 ├── Captured State
 └── Functions

27. A Production-Oriented Hybrid Design

A mature JavaScript application might look like:

┌──────────────────────────────┐
│        Controllers           │
└──────────────┬───────────────┘
               │
┌──────────────▼───────────────┐
│      Application Services    │
│             OOP              │
└──────────────┬───────────────┘
               │
┌──────────────▼───────────────┐
│       Domain Functions       │
│             FP               │
│                              │
│ Pure calculations            │
│ Validation                   │
│ Transformations              │
└──────────────┬───────────────┘
               │
┌──────────────▼───────────────┐
│      Infrastructure          │
│                              │
│ Database                     │
│ Redis                        │
│ APIs                         │
└──────────────────────────────┘

The important architectural idea is:

Keep business logic as pure as possible and isolate side effects.

For example:

const calculateOrderTotal = order => {
    // pure
};

class OrderService {
    constructor(repository) {
        this.repository = repository;
    }

    async createOrder(order) {
        const total = calculateOrderTotal(order);

        return this.repository.save({
            ...order,
            total
        });
    }
}

The calculation is pure.

The repository handles the side effect.

28. Practical Rules

When writing JavaScript applications, these rules are useful.

Rule 1: Prefer small functions

Instead of:

processEverything();

prefer:

validateOrder();
calculateTotal();
applyDiscount();
saveOrder();
sendNotification();

Rule 2: Minimize shared mutable state

Shared mutable state creates hidden dependencies.

Prefer:

const newState = updateState(oldState);

over uncontrolled global mutation.

Rule 3: Prefer composition over deep inheritance

Instead of:

A
└── B
    └── C
        └── D

consider:

A + capability1 + capability2 + capability3

Rule 4: Keep side effects at the boundaries

Pure:

const calculateTax = (price, rate) =>
    price * rate;

Side effect:

await database.save(order);

Don't mix them unnecessarily.

Rule 5: Use encapsulation where state has invariants

For example:

class BankAccount {
    #balance;

    withdraw(amount) {
        if (amount > this.#balance) {
            throw new Error("Insufficient funds");
        }

        this.#balance -= amount;
    }
}

The object protects its invariant.

29. Final Mental Model

The easiest way to remember the concepts is:

FUNCTIONAL PROGRAMMING
        │
        ├── Functions
        ├── Pure Functions
        ├── Immutability
        ├── Composition
        ├── Currying
        ├── Higher-Order Functions
        └── Recursion


OBJECT-ORIENTED PROGRAMMING
        │
        ├── Objects
        ├── Encapsulation
        ├── Abstraction
        ├── Inheritance
        ├── Polymorphism
        └── Composition


JAVASCRIPT
        │
        ├── Prototype-based
        ├── First-class Functions
        ├── Closures
        ├── Classes
        ├── Functional Features
        └── Object-oriented Features

The most important lesson is that JavaScript does not force you to choose one paradigm.

You can combine them.

For example:

class OrderService {
    constructor(repository) {
        this.repository = repository;
    }

    async process(order) {
        const validated = validateOrder(order);

        const total = calculateTotal(validated);

        const finalOrder = {
            ...validated,
            total
        };

        return this.repository.save(finalOrder);
    }
}

Here:

OrderService uses OOP
validateOrder can be a pure function
calculateTotal can be functional
{ ...validated } uses immutable-style updates
repository is encapsulated through the service
save() represents a side effect

This hybrid style is often more useful in real-world applications than trying to build an entire system using only FP or only OOP.

Conclusion

Functional Programming and Object-Oriented Programming are not simply collections of syntax features. They are different ways of reasoning about software.

FP focuses on:

Transforming data through predictable functions.

OOP focuses on:

Encapsulating state and behavior inside objects.

JavaScript gives developers the ability to use both.

Understanding prototypes explains how JavaScript objects actually work. Understanding composition helps avoid unnecessarily complex inheritance hierarchies. Higher-order functions, currying, and closures provide powerful functional abstractions. Pure functions and immutability make business logic easier to test and reason about. Private properties and methods provide strong encapsulation when objects need to protect their internal state.

The real goal is not to become "an FP developer" or "an OOP developer."

The goal is to become a developer who can choose the right abstraction for the problem.

Use objects when ownership and state matter.

Use functions when transformation and predictability matter.

Use composition when you need flexibility.

Use immutability when predictable state transitions matter.

And combine the paradigms when the system benefits from both.

Advanced Multithreading in Node.js

Abanoub Kerols — Mon, 03 Aug 2026 08:18:48 +0000

Event Loop Internals, libuv Architecture, V8 Isolates, Shared Memory, Worker Pools, and Performance Optimization

Introduction

Node.js has earned its reputation as a highly efficient runtime for building scalable network applications. One of the biggest misconceptions about Node.js is that it is "single-threaded." While JavaScript execution begins on a single thread, the Node.js runtime is built on top of a sophisticated architecture involving multiple native threads, asynchronous I/O, an event-driven execution model, and optional JavaScript worker threads for true parallel computation.

Understanding these internal mechanisms is essential for building high-performance backend systems, especially when working with CPU-intensive workloads, microservices, data processing pipelines, real-time analytics, or AI-powered applications.

This article explores Node.js from the inside out, covering the Event Loop, libuv, V8 Isolates, Worker Threads, shared memory, synchronization primitives, worker pools, and production performance tuning.

Node.js Runtime Architecture

A simplified Node.js runtime consists of several major components.

                    Node.js Runtime

                +---------------------+
                |    JavaScript Code  |
                +----------+----------+
                           |
                     V8 JavaScript Engine
                           |
                +----------+----------+
                |     Event Loop      |
                +----------+----------+
                           |
                        libuv
          +---------------+----------------+
          |                                |
     Thread Pool                  Operating System
          |                                |
   File System, Crypto,             Network, Timers,
   Compression, DNS                 TCP/UDP, Epoll, IOCP

Each layer has a specific responsibility.

V8 executes JavaScript.
The Event Loop schedules asynchronous callbacks.
libuv provides cross-platform asynchronous I/O.
The Operating System performs low-level operations.

Understanding V8

V8 is Google's high-performance JavaScript engine written in C++.

Its responsibilities include:

Parsing JavaScript
Compiling JavaScript
Optimizing frequently executed code
Garbage collection
Memory management
Executing JavaScript

Every Node.js process starts with one V8 instance.

However, every Worker Thread owns its own independent V8 instance.

This design is extremely important.

What is a V8 Isolate?

A V8 Isolate is an independent JavaScript execution environment.

Each isolate contains:

Heap
Stack
Global Object
Garbage Collector
Event Loop
Execution Context

Think of an isolate as a completely separate JavaScript world.

Node Process

      |

+-------------+
| Main Isolate|
+-------------+

      |

Worker Thread

      |

+--------------+
| Worker Isolate|
+--------------+

Variables inside one isolate cannot be directly accessed from another.

// main.js

let counter = 10;

Worker:

console.log(counter);

Output:

ReferenceError

Workers do not share JavaScript memory by default.

Why Use Isolates?

Isolates solve several difficult problems.

They provide:

Memory safety
Independent garbage collection
Crash isolation
Better scalability

If one Worker crashes, the main thread continues executing.

Deep Dive into the Event Loop

The Event Loop is responsible for deciding what JavaScript executes next.

Its job is to repeatedly inspect multiple queues and execute callbacks when they become ready.

Internally, every iteration is called a tick.

while(true){

    execute_ready_callbacks();

}

Of course, the actual implementation is significantly more complex.

Event Loop Phases

The Event Loop consists of six major phases.

          Event Loop

        +--------------+
        | Timers       |
        +--------------+
               |
               V
        +--------------+
        | Pending I/O  |
        +--------------+
               |
               V
        +--------------+
        | Idle/Prepare |
        +--------------+
               |
               V
        +--------------+
        | Poll         |
        +--------------+
               |
               V
        +--------------+
        | Check        |
        +--------------+
               |
               V
        +--------------+
        | Close        |
        +--------------+

Every phase has its own callback queue.

Timers Phase

Handles callbacks from:

setTimeout()

setInterval()

Example

setTimeout(() => {

    console.log("Timer");

},1000);

The callback is executed after the timer expires.

Pending Callbacks

Processes certain operating-system callbacks.

Examples:

TCP errors
Some network operations

Most developers rarely interact with this phase directly.

Idle / Prepare

Used internally by libuv.

Applications typically never execute code here.

Poll Phase

This is the most important phase.

It performs:

Waiting for I/O
Executing completed I/O callbacks
Determining whether timers are ready

Examples:

Database queries
Reading files
Incoming HTTP requests

Check Phase

Processes callbacks scheduled by:

setImmediate()

Example

setImmediate(() => {

    console.log("Immediate");

});

Close Callbacks

Handles resource cleanup.

Example

socket.on("close",()=>{
    console.log("Socket Closed");
});

Microtasks

Microtasks execute before the Event Loop continues.

Examples include:

Promise.resolve()

queueMicrotask()

process.nextTick()

Example

console.log(1);

Promise.resolve().then(()=>{

    console.log(2);

});

console.log(3);

Output

1
3
2

process.nextTick()

This queue has even higher priority.

console.log(1);

process.nextTick(()=>{

    console.log(2);

});

console.log(3);

Output

1
3
2

However,

process.nextTick()

executes before Promise callbacks.

Priority:

Current Code

↓

nextTick Queue

↓

Promise Queue

↓

Event Loop

Overusing process.nextTick() can starve the Event Loop because it continuously schedules work before the loop proceeds to later phases.

libuv Architecture

libuv is a cross-platform asynchronous library written in C.

Node.js relies heavily on it.

Responsibilities include:

Event Loop implementation
Thread Pool
TCP
UDP
Pipes
DNS
File System
Timers
Process management

Without libuv, Node.js would not exist in its current form.

libuv Thread Pool

The default thread pool contains:

4 Threads

Configurable via:

UV_THREADPOOL_SIZE=8

Supported tasks include:

fs
crypto
zlib
dns.lookup()

Not all asynchronous APIs use the thread pool.

Networking generally relies on the operating system's non-blocking I/O facilities instead.

CPU-Bound vs I/O-Bound Workloads

I/O-bound tasks spend most of their time waiting for external resources.

Examples:

HTTP requests
Database queries
Reading files
Network communication

CPU-bound tasks spend most of their time performing calculations.

Examples:

Image processing
AI inference
Video encoding
Compression algorithms
Mathematical simulations

Worker Threads are designed primarily for CPU-bound JavaScript.

Worker Threads Architecture

Node Process

        |

+--------------------+
| Main Thread        |
+--------------------+

        |

-------------------------------

Worker 1

Worker 2

Worker 3

Worker 4

Each Worker owns:

Separate Event Loop
Separate Heap
Separate Garbage Collector
Separate V8 Isolate

Workers execute JavaScript in parallel across multiple CPU cores.

Message Passing

Communication happens through structured messages.

Main Thread

worker.postMessage({

    task:100

});

Worker

parentPort.on("message",(msg)=>{

    console.log(msg.task);

});

Messages are serialized using the structured clone algorithm, similar to the Web Workers API.

Structured Clone Algorithm

Structured cloning copies JavaScript objects safely between isolates.

Supported examples include:

Objects
Arrays
Maps
Sets
TypedArrays
Dates

Unsupported examples include:

Functions
DOM nodes
Native resources
Closures

Copying very large objects repeatedly can become expensive.

Transferable Objects

Transferable Objects eliminate expensive copying.

Instead of cloning memory, ownership moves from one thread to another.

const buffer = new ArrayBuffer(1024);

worker.postMessage(

    buffer,

    [buffer]

);

After transfer:

Main thread:

Buffer

↓

Detached

Worker:

Buffer

↓

Owns Memory

Advantages:

Zero-copy transfer
Lower latency
Reduced memory pressure

Transferable Objects are ideal for large binary payloads such as images, audio, or serialized datasets.

SharedArrayBuffer

Sometimes copying data is undesirable.

Instead, multiple workers can access the same memory.

const shared = new SharedArrayBuffer(4);

const array = new Int32Array(shared);

Main thread:

array[0] = 50;

Worker:

console.log(array[0]);

Output

Both threads reference the same memory region.

Race Conditions

Shared memory introduces synchronization challenges.

Suppose two workers execute:

counter++;

Both threads may read the same value before writing back.

Example:

Worker A reads 5

Worker B reads 5

Worker A writes 6

Worker B writes 6

Expected:

Actual:

This is called a race condition.

Atomics

JavaScript provides atomic operations through the Atomics API.

Atomics.add(array,0,1);

This guarantees that the increment is performed safely.

Common atomic operations include:

add
sub
load
store
exchange
compareExchange
wait
notify

Atomics are essential whenever multiple threads modify shared memory concurrently.

Lock-Free Programming

Instead of traditional mutexes, JavaScript relies on atomic instructions.

Advantages:

Low latency
Reduced contention
High scalability

Disadvantages:

More difficult to design correctly
Easier to introduce subtle concurrency bugs

Lock-free algorithms should be used only when necessary and carefully tested.

Worker Pools

Creating Workers repeatedly is expensive.

Every Worker initializes:

V8
Heap
Garbage Collector
Event Loop

This startup cost can dominate small tasks.

Instead:

Request

↓

Worker Pool

↓

Existing Worker

Workers remain alive and are reused.

Piscina

Piscina is one of the most popular Worker Thread pool libraries for Node.js.

Features include:

Automatic scheduling
Worker reuse
Queue management
Task prioritization
Backpressure support
Async task execution
Performance monitoring

Example

const Piscina = require("piscina");

const piscina = new Piscina({

    filename:"worker.js"

});

const result = await piscina.run({

    number:1000

});

Piscina simplifies worker management and is a common choice for production services that perform repeated CPU-intensive tasks.

Memory Considerations

Each Worker owns:

Heap
Stack
Garbage Collector

Creating too many workers increases:

RAM usage
Context switching
CPU overhead

A common guideline is to keep the number of active workers close to the number of available CPU cores, then benchmark for your workload rather than assuming more workers always improve throughput.

Garbage Collection

Each isolate performs garbage collection independently.

Benefits:

No global pause
Better responsiveness
Lower contention

Large shared memory allocations are not managed like normal JavaScript objects, so developers should still monitor overall memory usage carefully.

Measuring Performance

Never assume optimization works.

Measure first.

Useful metrics include:

Response time
Throughput
CPU utilization
Memory usage
Event Loop delay
Worker queue length
Garbage collection pauses

Event Loop Lag

One important production metric is Event Loop latency.

A blocked Event Loop results in:

Slow API responses
Delayed timers
Poor user experience

Monitoring Event Loop delay can reveal CPU bottlenecks long before they become outages.

Benchmarking Strategy

A reliable benchmarking process typically follows these steps:

Establish a baseline without Worker Threads.
Identify CPU-bound hotspots using a profiler.
Introduce Worker Threads or a worker pool.
Measure latency, throughput, CPU utilization, and memory consumption under representative load.
Compare results across multiple runs.
Choose the design that improves real-world performance rather than microbenchmarks.

Benchmark in an environment that closely resembles production. Development laptops often produce misleading results due to different hardware and background workloads.

Profiling Tools

Common tools for production analysis include:

Node.js Inspector
Chrome DevTools
node --prof
clinic.js
autocannon for HTTP load testing
perf_hooks for application timing
Operating system tools such as top, htop, Task Manager, or Performance Monitor

Using profiling before optimization helps avoid spending time on code that is not actually limiting performance.

Best Practices

Keep the Event Loop responsive by avoiding long synchronous computations.
Use asynchronous APIs for I/O instead of creating Workers.
Reserve Worker Threads for CPU-bound JavaScript.
Prefer a Worker Pool such as Piscina instead of creating Workers per request.
Use Transferable Objects for large binary payloads to avoid unnecessary copying.
Use SharedArrayBuffer only when multiple threads truly need shared state.
Protect shared memory with Atomics whenever concurrent writes are possible.
Continuously monitor Event Loop latency, CPU utilization, memory usage, and queue lengths in production.
Benchmark every optimization and validate improvements under realistic workloads.

Conclusion

Node.js is far more than a single-threaded JavaScript runtime. Beneath its simple programming model lies a sophisticated architecture composed of the V8 engine, isolated JavaScript execution environments, the libuv asynchronous I/O library, a native thread pool, and Worker Threads capable of true parallel computation. Together, these components allow Node.js to efficiently handle thousands of concurrent connections while also scaling CPU-intensive workloads across multiple processor cores.

Mastering advanced multithreading in Node.js requires understanding how the Event Loop schedules work, how libuv delegates native operations, how V8 isolates provide memory isolation, how SharedArrayBuffer and Atomics enable safe shared-memory programming, and how worker pools such as Piscina reduce thread management overhead. Combined with careful profiling, benchmarking, and production monitoring, these techniques enable developers to build highly scalable, low-latency systems that make full use of modern multicore hardware while preserving the simplicity and productivity that have made Node.js one of the most popular server-side platforms.

Multithreading in Node.js: A Complete Guide with Theory and Practical Examples

Abanoub Kerols — Wed, 29 Jul 2026 07:48:34 +0000

When developers first learn Node.js, they often hear the phrase:

"Node.js is single-threaded."

While this statement is technically true, it is also incomplete.

Modern Node.js is capable of utilizing multiple threads, background workers, thread pools, and even multiple CPU cores. Understanding how these components work is essential for building high-performance applications.

This article explains the theory behind multithreading in Node.js, how it differs from traditional multithreading, and when to use Worker Threads, the Event Loop, the libuv Thread Pool, and the Cluster module.

What is a Thread?

A thread is the smallest unit of execution inside a process.

Imagine a restaurant.

The restaurant is the process.
Each chef is a thread.
Every chef can prepare food independently.

One chef means one task at a time.

Four chefs mean four tasks can run simultaneously.

Many programming languages create multiple threads that execute code in parallel.

Examples:

Java
C#
C++
Go

Node.js approaches concurrency differently.

Is Node.js Single-Threaded?

Yes—and no.

JavaScript Execution

JavaScript itself runs on a single main thread.

Only one JavaScript function executes at a time.

console.log("Task A");
console.log("Task B");
console.log("Task C");

Output

Task A
Task B
Task C

Everything executes sequentially.

However...

Node.js internally uses multiple threads for many operations.

Examples include:

File System
DNS
Compression
Cryptography
Worker Threads

So while JavaScript execution is single-threaded, Node.js as a runtime is definitely not.

Why Was Node.js Designed This Way?

Traditional servers often assign:

1 Request
      ↓
1 Thread

If 5,000 users connect simultaneously...

5000 Requests
↓

5000 Threads

Creating thousands of threads consumes huge amounts of:

Memory
CPU
Context switching

Node.js instead uses:

5000 Requests
↓

One Event Loop
↓

Non-blocking I/O

This dramatically reduces memory usage.

Process vs Thread

Process	Thread
Independent program	Part of a process
Own memory	Shares process memory
Heavy	Lightweight
Expensive to create	Cheap to create
Communication is slower	Communication is faster

Example

Google Chrome

Process
 ├── Thread
 ├── Thread
 ├── Thread
 └── Thread

Node.js normally runs as:

Process

Main Thread

But it can create additional threads when needed.

Understanding the Event Loop

The Event Loop is the heart of Node.js.

Imagine a receptionist.

People arrive with different requests.

Some requests take seconds.

Instead of waiting...

The receptionist sends long tasks elsewhere and immediately serves the next customer.

That is exactly how Node.js behaves.

Example

const fs = require("fs");

console.log("Start");

fs.readFile("data.txt", () => {
    console.log("Finished Reading");
});

console.log("End");

Output

Start
End
Finished Reading

Why?

Reading the file happens in the background.

The Event Loop continues processing other work.

Blocking vs Non-Blocking Code

Blocking

while(true){}

The Event Loop freezes.

Nothing else executes.

Non-blocking

setTimeout(() => {
    console.log("Done");
},1000);

console.log("Running...");

Output

Running...
Done

The timer runs asynchronously.

The Hidden Thread Pool

Node.js uses libuv, a powerful C library.

libuv maintains a thread pool.

Default size:

4 Threads

These threads perform expensive tasks.

Examples:

File system
DNS lookup
Crypto
Compression

Example

const crypto = require("crypto");

crypto.pbkdf2(
    "password",
    "salt",
    100000,
    64,
    "sha512",
    () => {
        console.log("Done");
    }
);

The hash calculation runs in a background thread.

The Event Loop remains free.

Increasing Thread Pool Size

Default:

4 Threads

Can be changed.

Linux

UV_THREADPOOL_SIZE=8 node app.js

Windows

set UV_THREADPOOL_SIZE=8
node app.js

Useful for heavy:

Crypto
File processing

Not useful for CPU-intensive JavaScript loops.

Why CPU-Heavy Tasks Are a Problem

Consider this function.

function heavyWork(){

    let total = 0;

    for(let i=0;i<1e10;i++){
        total += i;
    }

    return total;
}

Now imagine an Express server.

app.get("/",(req,res)=>{

    heavyWork();

    res.send("Done");

});

During calculation...

Every other request waits.

Even though Node.js supports asynchronous I/O, JavaScript itself is still executing on one thread.

Solution: Worker Threads

Node.js introduced Worker Threads to solve CPU-intensive problems.

Each Worker has:

Separate JavaScript engine
Separate Event Loop
Separate memory

Diagram

Main Thread

      |

-------------------------
|           |           |

Worker1   Worker2   Worker3

Each worker executes JavaScript independently.

Creating a Worker

main.js

const Worker = require("worker_threads").Worker;

const worker = new Worker("./worker.js");

worker.on("message",(msg)=>{
    console.log(msg);
});

worker.js

const { parentPort } = require("worker_threads");

let total = 0;

for(let i=0;i<1e9;i++){

    total += i;

}

parentPort.postMessage(total);

The heavy computation runs on another thread.

The main thread remains responsive.

Communication Between Threads

Workers communicate using messages.

Main Thread

worker.postMessage(100);

Worker

parentPort.on("message",(number)=>{

    console.log(number);

});

Everything is event-based.

Passing Data to Workers

worker.postMessage({
    name:"John",
    age:30
});

Worker

parentPort.on("message",(user)=>{

    console.log(user.name);

});

Shared Memory

Normally...

Workers do NOT share variables.

Instead...

They copy data.

However, Node.js supports

SharedArrayBuffer

which allows memory sharing.

Useful for:

Scientific computing
Large datasets
Machine Learning

Worker Lifecycle

Create Worker

↓

Execute

↓

Send Message

↓

Finish

↓

Terminate

Terminate manually

worker.terminate();

Error Handling

worker.on("error",(err)=>{

    console.log(err);

});

Exit event

worker.on("exit",(code)=>{

    console.log(code);

});

Worker Threads vs Child Process

Worker Thread	Child Process
Same process	New process
Lightweight	Heavy
Faster communication	Slower
Shared memory possible	No shared memory
Better for CPU work	Better for running external programs

Worker Threads vs Cluster

Cluster creates:

CPU Core 1

Node Process

CPU Core 2

Node Process

CPU Core 3

Node Process

Every process has:

Own Event Loop
Own Memory
Own V8 Engine

Cluster improves scalability for web servers.

Worker Threads improve CPU-heavy computations.

Worker Threads vs libuv Thread Pool

Many developers confuse these.

Worker Threads	libuv Thread Pool
Execute JavaScript	Execute native C/C++ operations
Created manually	Automatic
CPU-intensive work	I/O operations
Separate Event Loop	No JavaScript execution

Real-World Use Cases

Worker Threads are excellent for:

Image processing
Video encoding
PDF generation
Machine Learning inference
Encryption
Large mathematical calculations
Data analytics
CSV processing
Financial calculations
Compression

Avoid using them for:

Database queries
HTTP requests
Reading files
Network communication

Those are already asynchronous.

Performance Considerations

Creating a Worker has a cost.

Avoid:

One Request

↓

Create Worker

↓

Destroy Worker

Better:

Worker Pool

↓

Reuse Existing Workers

Libraries such as Piscina provide efficient worker pools.

Common Mistakes

Mistake 1

Using Workers for simple tasks.

Creating a Worker is slower than executing tiny calculations.

Mistake 2

Blocking the Event Loop.

while(true){}

Never perform long-running synchronous loops on the main thread.

Mistake 3

Confusing asynchronous programming with multithreading.

Asynchronous code is not automatically multithreaded.

await fetch(url);

This is asynchronous I/O, not parallel JavaScript execution.

Mistake 4

Ignoring message serialization costs.

Large objects passed between workers are copied unless transferable or shared-memory mechanisms are used.

Best Practices

Keep the Event Loop free for handling incoming requests.
Use asynchronous APIs for I/O operations whenever possible.
Use Worker Threads only for CPU-bound tasks.
Reuse workers through a worker pool instead of constantly creating new ones.
Monitor CPU and memory usage before introducing multithreading.
Transfer or share large buffers efficiently when performance matters.
Handle worker errors and exits gracefully.
Benchmark your application to verify that workers actually improve performance.

Summary

Node.js executes JavaScript on a single main thread, but the runtime itself uses multiple mechanisms to achieve concurrency and parallelism. The Event Loop efficiently handles asynchronous I/O without blocking, while the libuv Thread Pool transparently performs operations such as file system access, DNS lookups, cryptography, and compression. For CPU-intensive JavaScript tasks, Worker Threads enable true parallel execution by running JavaScript in separate threads with independent V8 instances and Event Loops. At a larger scale, the Cluster module distributes incoming requests across multiple Node.js processes to utilize all available CPU cores.

Choosing the right tool depends on the nature of the workload: use asynchronous I/O for network and file operations, rely on the libuv Thread Pool for supported native tasks, adopt Worker Threads for computationally expensive JavaScript, and use clustering when scaling web servers across multiple cores. Understanding these components allows developers to build Node.js applications that are responsive, scalable, and capable of efficiently utilizing modern multi-core hardware.

DEV Community: Abanoub Kerols

Using Next.js as a Backend for Frontend (BFF)

What is a BFF?

Next.js as a BFF

API Aggregation

Response Transformation

Authentication

The Important Architectural Boundary

Final Architecture

The key idea

Dependency Injection in Angular: From Constructor Injection to Modern DI

1. What Is Dependency Injection?

2. Dependency Injection vs Dependency Inversion

Dependency Injection

Dependency Inversion

3. What Is a Dependency?

4. The Three Important DI Concepts

Token

Provider

Injector

5. The Old Angular DI Model

6. Constructor Injection

Why constructor injection was popular

7. Modern Angular DI: inject()

8. Constructor Injection vs inject()

Old style

Modern style

9. The Injection Context

10. Valid Places for inject()

Field initializer

Constructor

Provider factory

InjectionToken factory

Functional route guard

11. Why inject() Fails in Async Code

12. runInInjectionContext()

13. Injector

14. @Injectable()

15. providedIn

16. providedIn: 'root'

17. providedIn: 'platform'

18. The Historical providedIn: 'any'

19. providedIn: NgModule

20. Manual Providers

21. Component-Level Providers

22. The Provider Shorthand

Provider Recipes

23. useClass

24. useValue

25. Why You Need InjectionToken

26. InjectionToken

27. InjectionToken Identity Matters

28. useFactory

29. Factory Dependencies with deps

30. useExisting

31. useExisting vs useClass

useClass

useExisting

32. multi: true

33. providers vs viewProviders

34. Angular's Injector Hierarchy

35. EnvironmentInjector

36. ElementInjector

37. How Angular Resolves a Dependency

38. Provider Override

39. Self

40. SkipSelf

41. Optional

42. Host

43. Combining DI Modifiers

44. The Old Decorator Modifiers

45. @Inject()

46. forwardRef()

47. NgModule-Based DI

48. Modern Standalone DI

49. Provider Functions

50. Feature Functions: withX()

51. InjectionToken with a Factory

52. DI and Testing

53. DI and Mocking

7. Modern Angular DI: `inject()`

8. Constructor Injection vs `inject()`

10. Valid Places for `inject()`

11. Why `inject()` Fails in Async Code

12. `runInInjectionContext()`

13. `Injector`

14. `@Injectable()`

15. `providedIn`

16. `providedIn: 'root'`

17. `providedIn: 'platform'`

18. The Historical `providedIn: 'any'`

19. `providedIn: NgModule`

23. `useClass`

24. `useValue`

25. Why You Need `InjectionToken`

26. `InjectionToken`

28. `useFactory`

29. Factory Dependencies with `deps`

30. `useExisting`

31. `useExisting` vs `useClass`

`useClass`

`useExisting`

32. `multi: true`

33. `providers` vs `viewProviders`

39. `Self`

40. `SkipSelf`

41. `Optional`

42. `Host`

45. `@Inject()`

46. `forwardRef()`

50. Feature Functions: `withX()`

51. `InjectionToken` with a Factory

83. Building a `provideTasks()` API

84. Advanced `provideX()` Architecture

85. `viewProviders` in Real Applications

90. Common Error: `inject()` Outside Context

92. Common Error: Confusing `useClass` and `useExisting`

93. Common Error: Making Everything `providedIn: 'root'`

1. Prefer `providedIn: 'root'` for true application-wide services

3. Prefer `inject()` for modern Angular code

5. Use `InjectionToken` for interfaces and configuration

7. Use `useExisting` when you need an alias to the same instance

8. Use `multi` for extensible collections