DEV Community: Adarsh Hasnah

Kebab-Case Filenames and PascalCase Classes: Naming Conventions That Scale

Adarsh Hasnah — Tue, 27 Jan 2026 08:50:21 +0000

Naming conventions are not cosmetic.
They are how developers understand intent at scale.

In modern JavaScript and TypeScript projects, inconsistent naming leads
to:

slower onboarding
harder navigation
unnecessary debates in code reviews

After years of working with Node.js, TypeScript, and modular systems,
one combination consistently delivers clarity with minimal friction:

kebab-case for filenames
Explicit responsibility-based suffixes
PascalCase for classes and public APIs

This article explains why these naming conventions work, and why
they scale better than common alternatives.

Why Naming Conventions Matter in TypeScript Projects

File and symbol names are human interfaces.

Good naming conventions should be:

Predictable
Easy to scan
Cross-platform safe
Tooling-friendly
Explicit about responsibility

The goal is not cleverness --- it's removing cognitive load.

Why Use `kebab-case` for Filenames?

Example (Suffix-Enforced)

user.service.ts
email-notification.controller.ts
cache-entry.repository.ts
data-cleanup.job.ts

Pattern:

<domain-or-feature>.<responsibility>.ts

1. Cross-Platform Safety

Operating systems treat filenames differently:

Windows / macOS → case-insensitive
Linux → case-sensitive

These two files are a common source of bugs:

UserService.ts
userService.ts

Using kebab-case eliminates ambiguity and avoids OS-specific issues.

2. Native to Web and Tooling Ecosystems

kebab-case is already the default for:

URLs
npm packages
Docker images
GitHub repositories
CI/CD pipelines

Using it for filenames creates consistency across your entire
toolchain.

3. Better Readability for Long Filenames

Long filenames are unavoidable in real-world systems.

emailNotificationRetryConfigurationService.ts

email-notification-retry-configuration.service.ts

kebab-case improves scannability and reduces visual parsing effort.

Responsibility-Based Suffixes Improve Clarity

While kebab-case improves readability, suffixes communicate
intent.

Common Responsibility Suffixes

.entity.ts
.value-object.ts
.repository.ts
.service.ts
.use-case.ts
.controller.ts
.route.ts
.dto.ts
.mapper.ts
.job.ts
.event.ts
.policy.ts

Why the Responsibility Suffix Comes Last

Responsibility is always the final signal:

*.service.ts
*.repository.ts
*.controller.ts

Benefits:

Faster scanning
Easier filtering
Tooling enforcement (linting, boundaries)
Clear architectural intent

You should understand what a file is without opening it.

Avoid Embedding Responsibility in Names

❌ Avoid:

user-service.ts
email-notification-controller.ts

✅ Prefer:

user.service.ts
email-notification.controller.ts

This keeps responsibility explicit, standardized, and enforceable.

Why Use `PascalCase` for Classes?

Example

class UserService {}
class EmailNotificationSender {}
class DataCleanupJob {}

1. Immediate Type Signaling

PascalCase instantly signals:

This is a class, type, or conceptual construct.

This distinction matters when scanning large codebases.

2. Aligns With TypeScript Standards

In TypeScript: - Classes → PascalCase - Interfaces → PascalCase -
Types → PascalCase

interface MessageSender {}
class SmtpMessageSender implements MessageSender {}

Consistency reduces mental overhead and ambiguity.

3. File-to-Class Naming Symmetry

user.service.ts            → class UserService
email-notification.job.ts  → class EmailNotificationJob
cache-entry.entity.ts      → class CacheEntry

This symmetry makes navigation predictable and intuitive.

Naming Functions: PascalCase vs camelCase

Practical Rule

Public / exported / use-case functions → PascalCase
Local helper functions → camelCase

export function RegisterUser() {}
export function SendNotification() {}

function sanitizeInput() {}
function retryWithBackoff() {}

PascalCase functions read like actions, not utilities.

Why Not `camelCase` or `snake_case` for Filenames?

`snake_case`

Rare in modern JS/TS ecosystems
Uncommon in URLs and tooling
Inconsistent with npm and Docker norms

`camelCase`

Harder to scan
Case-sensitivity issues
Visually dense in file explorers

For filenames, kebab-case is the most readable and compatible option.

Reduced Cognitive Load Is the Real Benefit

Once these conventions are established: - naming debates disappear -
navigation becomes intuitive - onboarding gets faster

Good conventions fade into the background --- exactly where they belong.

TL;DR: Recommended Naming Conventions

Filenames

kebab-case + explicit responsibility suffix

Classes / Types

PascalCase

Local variables & helpers

camelCase

Final Thoughts

Clean naming conventions are not about style.\
They're about clarity, scalability, and developer experience.

When filenames communicate responsibility and symbols reflect intent,
your codebase becomes easier to reason about --- today and years from
now.

Consistency beats cleverness. Every time.

Node.js Production Flags: Which Runtime Flags Are Safe (and Which Will Break Your App)

Adarsh Hasnah — Tue, 16 Dec 2025 10:26:25 +0000

Node.js provides dozens of runtime flags, but very few are safe to use in production.

Misusing Node.js flags is a common cause of:

unstable performance
memory crashes
unpredictable behavior under load

This article explains Node.js production flags that are actually safe, which ones should be avoided, and how to think about runtime flags as part of your production contract.

If you run Node.js in production (Express, Fastify, containers, Kubernetes), this guide is for you.

What Are Node.js Runtime Flags?

Node.js runtime flags are command-line options passed to the node process that modify:

memory behavior
error handling
module loading
debugging and diagnostics

Example:

node --enable-source-maps dist/server.js

In production, runtime flags should be deliberate and minimal.

A Simple Rule for Node.js Production Flags

Before enabling any Node.js flag in production, ask:

Does this flag improve correctness, stability, or observability?

If the answer is “developer convenience” or “local debugging”, it does not belong in production.

Safe Node.js Flags for Production

These Node.js runtime flags are widely used in real production systems and have predictable behavior.

`--enable-source-maps` (Strongly Recommended)

node --enable-source-maps dist/server.js

What it does

Maps JavaScript stack traces back to the original source files.

Why it’s safe in production

Essential for TypeScript applications
Dramatically improves error diagnostics
Negligible performance overhead

If you run Node.js with TypeScript and don’t enable source maps, production debugging becomes guesswork.

`--max-old-space-size` (Memory Control)

node --max-old-space-size=1024 dist/server.js

What it does

Limits the V8 heap size in megabytes.

Why it’s important

Prevents unexpected out-of-memory kills
Makes Node.js memory usage predictable
Essential in Docker and Kubernetes

Best practice

Set this to 70–80% of container memory.

`--unhandled-rejections=strict` (Correctness)

node --unhandled-rejections=strict dist/server.js

What it does

Crashes the process on unhandled promise rejections.

Why it belongs in production

Exposes broken async code immediately
Prevents silent data corruption
Forces correct error handling

Unhandled promise rejections are one of the most common hidden Node.js production bugs.

`--import` / `-r` (Preloading for Instrumentation)

node --import ./dist/otel.js dist/server.js

or:

node -r ./dist/otel.js dist/server.js

What it does

Loads a module before your application starts.

Valid production use cases

OpenTelemetry instrumentation
Global diagnostics
Performance monitoring setup

Avoid

Business logic
Application configuration
Feature flags

Node.js preloading should prepare the runtime — not change application behavior.

`--trace-warnings` (Conditional Use)

node --trace-warnings dist/server.js

What it does

Adds stack traces to runtime warnings.

When to use

Staging environments
Short-term production debugging

Avoid leaving this enabled permanently due to log noise.

Node.js Flags You Should Avoid in Production

Many Node.js flags exist for development or debugging and should never run in production.

Development-Only Node.js Flags

Flag	Why It’s Unsafe
`--watch`	Auto-restart breaks stability
`--inspect`, `--inspect-brk`	Security risk
`--loader ts-node/esm`	Runtime TypeScript compilation
`ts-node`, `tsx`	Dev tooling only

Experimental Node.js Flags

Flag	Risk
`--experimental-*`	Unstable behavior
`--experimental-fetch` (older Node)	Inconsistent semantics
`--experimental-vm-modules`	Tooling only

If a flag is marked experimental, it is not production-ready.

High-Overhead Diagnostic Flags

Flag	Why to Avoid
`--trace-gc`	Severe performance impact
`--prof`	Profiling only
`--trace-events-enabled`	Heavy overhead

Use these flags only during controlled profiling sessions.

Node.js Runtime Flags vs Application Code

A healthy production system respects this boundary:

Node.js flags configure the runtime
Application code defines behavior

If a flag:

changes request handling
toggles features
alters business logic

…it’s being misused.

Recommended Node.js Production Startup Command

Most production Node.js applications need very few flags:

node \
  --enable-source-maps \
  --max-old-space-size=1024 \
  --unhandled-rejections=strict \
  dist/server.js

Add --import only when you use runtime instrumentation like OpenTelemetry.

Why Node.js Flags Are Part of Your Production Contract

Node.js runtime flags are not an implementation detail.

They directly affect:

memory behavior
error handling
observability

Changing flags is a production change, just like changing container limits or deployment configs.

Final Thoughts on Node.js Production Flags

Node.js gives you powerful runtime controls.

Production systems should use as few of them as possible.

If your application needs many Node.js flags to stay stable, the problem isn’t the flags — it’s the architecture.

Keep the Node.js runtime boring.

Boring systems are reliable systems.

A Practical Introduction to AsyncLocalStorage in Node.js (With Real Use Cases)

Adarsh Hasnah — Fri, 12 Dec 2025 06:50:13 +0000

AsyncLocalStorage (ALS) is a powerful but often misunderstood feature in Node.js. At its core, ALS provides a reliable way to maintain execution context across asynchronous operations—a challenge every Node.js backend eventually faces.

If you’ve ever needed to keep track of metadata such as request IDs, tenant identifiers, locales, or feature flags across nested async/await calls, ALS is the tool designed for that job.

This article explains what AsyncLocalStorage is, how it works, and how to apply it effectively using practical examples.

What Is AsyncLocalStorage in Node.js?

AsyncLocalStorage is part of the async_hooks module and functions similarly to thread-local storage in multi-threaded languages—except adapted for Node’s event-loop and asynchronous model.

It creates a context store that persists across all asynchronous boundaries triggered within a specific scope.

This enables predictable context propagation through:

Promises
Timers (setTimeout, setInterval)
Database clients
External API calls
Streams
Message queue handlers
Any nested async function

Core benefit: You no longer need to pass metadata manually through every function call.

Why AsyncLocalStorage Matters for Modern Node.js Applications

Maintaining context is important for:

Request correlation and structured logging
Distributed tracing
Multi-tenant routing
User or locale propagation
Feature flag consistency
Tracking background job executions

ALS is fundamentally about context propagation, not just logging.

Architecture: How ALS Propagates Context

Incoming Request / Task
        │
        ▼
┌────────────────────────┐
│ Initialize ALS Context │  ← store.run(...)
└───────────┬────────────┘
            │
            ▼
Handlers → Services → Async Calls → DB/API → Response
            │
            ▼
   The ALS context remains accessible everywhere

ALS creates a scope once, and all subsequent async operations continue to use the same context.

Minimal AsyncLocalStorage Example

import { AsyncLocalStorage } from 'node:async_hooks';

const store = new AsyncLocalStorage();

store.run({ value: 123 }, () => {
  setTimeout(() => {
    console.log('Context:', store.getStore());
  }, 50);
});

Output:

Context: { value: 123 }

Even across timeout boundaries, the context is preserved.

Using AsyncLocalStorage in an Express Application

Initialize Context per Request

import { AsyncLocalStorage } from 'node:async_hooks';
import express from 'express';
import { randomUUID } from 'crypto';

const asyncStore = new AsyncLocalStorage();
const app = express();

app.use((req, res, next) => {
  const context = {
    requestId: req.headers['x-request-id'] || randomUUID()
  };

  asyncStore.run(context, () => next());
});

Access the Context Later in the Flow

function getContext() {
  return asyncStore.getStore();
}

app.get('/users', async (req, res) => {
  await new Promise(resolve => setTimeout(resolve, 100));

  const ctx = getContext();

  console.log('Request ID:', ctx.requestId);

  res.json({ requestId: ctx.requestId });
});

This is the classic request ID correlation pattern and is widely used for production observability.

Other Practical AsyncLocalStorage Use Cases

Beyond correlation IDs, ALS supports several operational patterns:

1. Multitenancy Context

asyncStore.run({ tenantId: 'acme' }, () => handleRequest());

2. Locale & Internationalization

{ locale: req.headers['accept-language'] }

3. Feature Flag Snapshot

{ featureFlags: evaluateFlags(user) }

4. Background Job Tracking

worker.on('job', job => {
  asyncStore.run({ jobId: job.id }, () => processJob(job));
});

These examples rely on the same mechanism: execution-scoped context.

When Should You Use AsyncLocalStorage?

Use Case	ALS Recommended?
Request/Execution scoped metadata	✔ Yes
Request ID correlation	✔ Yes
Distributed tracing	✔ Yes
Multi-tenant context	✔ Yes
Passing large mutable objects	✘ No
Global config	✘ No

ALS should store lightweight metadata, not application state.

FAQ: Common Questions About AsyncLocalStorage

What is AsyncLocalStorage used for in Node.js?

It maintains execution-scoped context across async operations, enabling request correlation, multitenancy, tracing, and more.

Is AsyncLocalStorage only for request IDs?

No. Request IDs are just one example. ALS can hold any metadata relevant to the async execution scope.

Does ALS work with async/await?

Yes. ALS propagates through promises, timers, callbacks, and most async libraries.

Can ALS be used outside Express?

Yes. It works in Fastify, NestJS, message queues, CRON jobs, and any async workflow.

Is there a performance cost?

A small one, but acceptable for most workloads. ALS is used by major frameworks and tracing tools.

Summary

AsyncLocalStorage is a foundational tool for building reliable, observable Node.js applications. It provides a clean and efficient way to maintain execution context without manually passing metadata through every function. While request ID correlation is the most common pattern, ALS supports many other practical use cases such as multitenancy, localization, feature flags, and background job correlation.

If you're building production-grade Node.js services, understanding ALS will significantly improve your architecture, debugging capabilities, and observability.

Mastering Request Correlation: The Key to Debugging Microservices Without Losing Your Mind

Adarsh Hasnah — Thu, 11 Dec 2025 06:41:01 +0000

Summary:
Ever struggled debugging microservices? Request correlation is the missing thread that connects logs, metrics, and traces. This practical, story-driven guide explains why it matters, how it works, and how to implement it cleanly—with diagrams and real examples.

Distributed systems are fun—right up until something goes wrong.

If you’ve ever tailed logs from multiple services at 1AM, hopping between dashboards while your coffee goes cold, trying to explain why a simple request took twelve seconds… then you’ve already met the exact problem request correlation exists to solve.

Most teams only start caring about it once things catch fire. But once you implement it properly, you’ll wonder how you ever operated without it.

What Request Correlation Actually Is

Request correlation is simply the idea of giving every incoming request a unique ID—and then making sure that ID travels through every service, log entry, async job, and metric connected to that request.

In microservices, this is the closest thing we have to a universal translator.

Here’s what the “story thread” looks like as a request moves through your system:

Client
   │
   ▼
┌─────────────────────────────┐
│         API Gateway         │
│   assigns X-Request-ID      │
│            abc123           │
└───────────────┬─────────────┘
                │
      X-Request-ID: abc123
                │
                ▼
       ┌───────────────────┐
       │     Service A     │
       │ logs cid=abc123   │
       └──────────┬────────┘
                  │
        X-Request-ID: abc123
                  │
                  ▼
       ┌───────────────────┐
       │     Service B     │
       │ logs cid=abc123   │
       └──────────┬────────┘
                  │
        X-Request-ID: abc123
                  │
                  ▼
       ┌───────────────────┐
       │     Service C     │
       │ logs cid=abc123   │
       └───────────────────┘

One request, one ID, one coherent story.

Why Request Correlation Matters for Distributed Systems

1. Debugging becomes sane again

Without correlation IDs, debugging microservices feels like detective work with no fingerprints.

With them, one search gives you the entire request journey.

2. You finally see the real bottlenecks

A slow endpoint is usually not the culprit—it’s one of the services it calls.

Correlation exposes the actual hotspot.

3. Your logs become dramatically more valuable

Most logs tell you what happened.

Correlation tells you why and in which order.

4. Observability becomes a unified system

Correlation IDs are the glue between logs, metrics, and traces:

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Logs    │ --> │  Metrics │ --> │  Traces  │
└────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                │
     └────────────── correlation ID ───┘

When everything shares the same ID, your observability stack becomes one narrative instead of three silos.

Where Teams Get Request Correlation Wrong

🚫 Mistake 1 — Not propagating the ID to downstream services

If Service A creates it but doesn’t pass it to Service B, the trail goes cold.

🚫 Mistake 2 — Overwriting an existing client-provided ID

If the request already has X-Request-ID or traceparent, keep it.

You’re continuing a story, not starting a new one.

🚫 Mistake 3 — Logging without structure

Correlation IDs buried inside text logs are nearly useless.

Use JSON logs so tools can index them properly.

🚫 Mistake 4 — Treating correlation as optional

It must be consistent.

It should behave like authentication: always present, always accurate.

A Practical Example Using Node.js and `AsyncLocalStorage`

Here’s a clean and robust approach for correlation in Node.js:

import { AsyncLocalStorage } from 'node:async_hooks';
import crypto from 'node:crypto';

const storage = new AsyncLocalStorage();

export function correlationMiddleware(req, res, next) {
  const correlationId = req.headers['x-request-id'] || crypto.randomUUID();

  storage.run({ correlationId }, () => {
    res.setHeader('x-request-id', correlationId);
    next();
  });
}

export function getCorrelationId() {
  return storage.getStore()?.correlationId;
}

Behind the scenes:

HTTP request arrives
        │
        ▼
 create context { cid: abc123 }
        │
        ▼
 handler → DB call → internal fn → logger
 (context preserved the entire time)

This is what turns spaghetti logs into a timeline you can trust.

Debugging With Correlation (the good part)

This is where you feel the payoff:

Request ID: abc123
───────────────────────────────────────────
[Gateway]      received request
[Service A]    validated payload
[Service A]    calling Service B
[Service B]    fetching user profile
[Service C]    cache miss (140ms)
[Service B]    returned profile
[Service A]    sent final response
───────────────────────────────────────────
Total time: 412ms
Bottleneck: Service C

No guessing.
No grepping through chaos.
Just answers.

Debugging Without Correlation (the old way)

2025-01-11T10:02:33Z Service A - incoming call
2025-01-11T10:02:33Z Service B - fetch user
2025-01-11T10:02:33Z Service C - cache miss
2025-01-11T10:02:34Z Service B - returning data
2025-01-11T10:02:34Z Service A - responding

Which logs belong to which user?
Which request failed?
Which step was slow?

It’s like being handed random pages from random books and told to interpret the story.

The Real Lesson

If your system is growing, add request correlation now.
If it’s already misbehaving, add it immediately.

It’s one of the smallest pieces of code you’ll ever write…
…for one of the biggest improvements in how you understand and operate your system.

Once you follow a single ID end-to-end and it leads you straight to the issue, you’ll wonder how you ever debugged without it.

What about you?

Have you implemented request correlation in your stack?
What tools or patterns worked best for you?

I’d love to hear how you approach debugging in distributed systems.