DEV Community: Alex Chen

CSS Layout in 2026: Flexbox, Grid, and When to Use Each (2026)

Alex Chen — Sat, 23 May 2026 20:35:05 +0000

CSS Layout in 2026: Flexbox, Grid, and When to Use Each (2026)

Stop guessing with margins and floats. Here's how modern CSS layout actually works.

The Evolution

1990s: Table layouts (don't ask)
2000s: Float-based layouts (clearfix hacks everywhere)
2010s: Flexbox (one-dimensional layout savior)
2020s: Grid (two-dimensional layout done right)
2026: Flexbox + Grid + Container Queries = complete toolkit

Quick Decision Guide

Need to lay out items in ONE direction?
→ Use FLEXBOX (row or column)

Need to lay out items in TWO directions (rows AND columns)?
→ Use GRID

Need a component that adapts to its container size?
→ Use CONTAINER QUERIES + Grid/Flexbox

Simple centering?
→ Either works (Flexbox is shorter)

Flexbox Deep Dive

The Core Concept

/* Flexbox = one-dimensional layout */
/* Items flow in either a ROW or a COLUMN */

.container {
  display: flex;
  /* Main axis: horizontal by default */
  /* Cross axis: perpendicular to main axis */
}

Direction & Wrapping

.container {
  display: flex;

  /* Main axis direction */
  flex-direction: row;         /* left → right (default) */
  flex-direction: row-reverse;  /* right → left */
  flex-direction: column;       /* top → bottom */
  flex-direction: column-reverse;/* bottom → top */

  /* Wrapping behavior */
  flex-wrap: nowrap;   /* single line, shrink if needed (default) */
  flex-wrap: wrap;     /* multi-line, flows to next line */
  flex-wrap: wrap-reverse; /* wraps in reverse order */
}

/* Shorthand */
flex-flow: row wrap; /* direction + wrap together */

Alignment (This Is Where Most People Get Stuck)

.container {
  display: flex;

  /* MAIN AXIS alignment (justify) */
  justify-content: flex-start;  /* pack to start (default) */
  justify-content: flex-end;    /* pack to end */
  justify-content: center;      /* center horizontally */
  justify-content: space-between; /* equal space BETWEEN items */
  justify-content: space-around;  /* equal space AROUND items */
  justify-content: space-evenly;  /* exactly equal space everywhere */

  /* CROSS AXIS alignment (align) — controls the OTHER dimension */
  align-items: stretch;    /* stretch to fill (default) */
  align-items: flex-start; /* align to cross-axis start */
  align-items: flex-end;   /* align to cross-axis end */
  align-items: center;     /* center vertically */
  align-items: baseline;   /* align text baselines */
}

/* Visual reference:

   justify-content (main axis →):
   ┌─────────────────────────────┐
   │ [item]   [item]   [item]  │  space-between
   │ [item] [item] [item] [item]│  space-evenly
   │        [item] [item]       │  center

   align-items (cross axis ↓):
   ┌──┐
   │  │ item  flex-start
   ├──┤
   │  │ item  center
   ├──┤
   │  │ item  flex-end
   └──┘
*/

Item-Level Control

.item {
  /* How much can this item grow? */
  flex-grow: 0;   /* don't grow (default) */
  flex-grow: 1;   /* grow equally with siblings */
  flex-grow: 2;   /* grow 2x as much as flex-grow:1 siblings */

  /* How much can this item shrink? */
  flex-shrink: 1;  /* shrink equally (default) */
  flex-shrink: 0;  /* never shrink (important for icons/buttons!) */

  /* Base size before growing/shrinking */
  flex-basis: auto; /* use content size (default) */
  flex-basis: 200px; /* start at 200px */
  flex-basis: 0;     /* start at 0 (useful for equal-width items) */

  /* Override container's align-items for this specific item */
  align-self: center; /* this item centers itself */
  align-self: flex-start; /* this item sticks to start */
}

/* Shorthand: grow | shrink | basis */
flex: 1;        /* flex-grow: 1; flex-shrink: 1; flex-basis: 0% */
flex: 0 0 auto; /* don't grow, don't shrink, use content size */
flex: 1 1 200px; /* grow, shrink, start at 200px */

/* THE magic trick: equal-width children */
.equal-children > * {
  flex: 1;
}

Real-World Flexbox Patterns

/* Pattern 1: Perfect centering (the #1 use case) */
.center-all {
  display: flex;
  justify-content: center;
  align-items: center;
  min-height: 100vh;
}

/* Pattern 2: Navbar */
.navbar {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 1rem 2rem;
}
.navbar > .logo { flex-shrink: 0; }
.navbar > .nav-links { display: flex; gap: 1rem; }

/* Pattern 3: Card with sticky footer */
.card {
  display: flex;
  flex-direction: column;
}
.card-body { flex: 1; }  /* Takes all available space */
.card-footer { /* normal size, stays at bottom */ }

/* Pattern 4: Media object (avatar + text) */
.media-object {
  display: flex;
  align-items: flex-start;
  gap: 1rem;
}
.media-object > .avatar {
  flex-shrink: 0; /* Avatar never squishes */
  width: 48px;
  height: 48px;
}
.media-object > .content { flex: 1; } /* Text takes rest */

/* Pattern 5: Form row */
.form-row {
  display: flex;
  gap: 1rem;
  flex-wrap: wrap; /* Responsive: wraps on small screens */
}
.form-row > * {
  flex: 1 1 200px; /* Min 200px, grow equally */
}

/* Pattern 6: Loading spinner overlay */
.loading-overlay {
  position: fixed;
  inset: 0;
  display: flex;
  justify-content: center;
  align-items: center;
  background: rgba(0, 0, 0, 0.5);
}

CSS Grid Deep Dive

The Core Concept

/* Grid = two-dimensional layout */
/* Define rows AND columns explicitly */

.container {
  display: grid;
  /* Define columns */
  grid-template-columns: 200px 1fr 200px;
  /* Define rows */
  grid-template-rows: auto 1fr auto;
  /* Gap between cells */
  gap: 1rem;
}

The fr Unit (Game Changer)

/* fr = "fraction of available space" */

.grid-3-equal {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr; /* Three equal columns */
}

.grid-sidebar {
  display: grid;
  grid-template-columns: 250px 1fr; /* Fixed sidebar + fluid content */
}

.grid-complex {
  display: grid;
  grid-template-columns: 200px 1fr 300px; /* Left nav + content + right panel */
  grid-template-rows: 60px 1fr 40px; /* Header + main + footer */
}

/* repeat() saves typing */
.grid-12 {
  display: grid;
  grid-template-columns: repeat(12, 1fr); /* 12-column grid system */
}

/* minmax() for responsive without media queries */
.responsive-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  /* Automatically creates as many 250px+ columns as fit */
  gap: 1rem;
}

Placing Items

.container {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  grid-template-rows: auto auto auto;
  gap: 1rem;
}

/* Method 1: Auto-placement (items flow in order) */
.item { /* just place them, they'll fill cells */ }

/* Method 2: Line-based placement */
.header {
  grid-column: 1 / -1; /* From column 1 to last column */
  grid-row: 1 / 2;
}

.sidebar {
  grid-column: 1 / 2;
  grid-row: 2 / 4; /* Spans rows 2 and 3 */
}

.main {
  grid-column: 2 / -1;
  grid-row: 2 / 3;
}

/* Method 3: Named areas (most readable!) */
.dashboard {
  display: grid;
  grid-template-areas:
    "header header header"
    "sidebar main main"
    "sidebar footer footer";
  grid-template-columns: 200px 1fr 1fr;
  grid-template-rows: auto 1fr auto;
  gap: 1rem;
}

.header  { grid-area: header; }
.sidebar { grid-area: sidebar; }
.main    { grid-area: main; }
.footer  { grid-area: footer; }

/* Method 4: span keyword */
.featured {
  grid-column: span 2; /* Spans 2 columns */
  grid-row: span 2;    /* Spans 2 rows */
}

Alignment in Grid

.container {
  display: grid;

  /* Align content within grid area */
  justify-items: start;   /* horizontal alignment inside cell */
  align-items: start;     /* vertical alignment inside cell */
  /* Values: start, end, center, stretch */

  /* Align entire grid tracks when smaller than container */
  justify-content: center; /* center the whole grid */
  align-content: center;

  /* Per-item override */
  .specific-item {
    justify-self: end;
    align-self: center;
  }
}

Real-World Grid Patterns

/* Pattern 1: Holy Grail Layout */
.holy-grail {
  display: grid;
  grid-template:
    "header header header" auto
    "nav    content aside" 1fr
    "footer footer footer" auto
    / 200px 1fr 200px;
  min-height: 100vh;
  gap: 1rem;
}

/* Pattern 2: Card Grid (responsive) */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: 1.5rem;
}
/* No media queries needed! Cards reflow automatically */

/* Pattern 3: Dashboard */
.dashboard-grid {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  grid-template-rows: auto 1fr auto;
  gap: 1rem;
}
.widget-wide  { grid-column: span 2; }
.widget-tall   { grid-row: span 2; }

/* Pattern 4: Image gallery (Masonry-like) */
.gallery {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  grid-auto-rows: 200px;
  gap: 0.5rem;
}
.gallery img:nth-child(5n+1) { grid-row: span 2; } /* Some images taller */

/* Pattern 5: Form layout */
.form-grid {
  display: grid;
  grid-template-columns: auto 1fr;
  gap: 1rem;
  align-items: center;
}
.form-grid label { text-align: right; }
.form-grid .full-width { grid-column: span 2; }

/* Pattern 6: Feature comparison table */
.comparison-table {
  display: grid;
  grid-template-columns: 2fr repeat(3, 1fr);
  gap: 1px;
  background: #e0e0e0; /* Gap color = border effect */
}
.comparison-table > * {
  background: white;
  padding: 1rem;
}

Container Queries (2026 Essential)

/* Media queries: style based on VIEWPORT size */
/* Container queries: style based on CONTAINER size */

/* Define a container */
.card-container {
  container-type: inline-size;
  container-name: card;
}

/* Style based on container width, not viewport! */
@container card (min-width: 400px) {
  .card-inner {
    display: grid;
    grid-template-columns: 200px 1fr;
  }
}

@container card (min-width: 600px) {
  .card-inner {
    grid-template-columns: 250px 1fr 150px;
  }
}

/* This means your component looks great ANYWHERE:
   In a sidebar, in a modal, in a grid cell, in full page.
   The component adapts to its own space! */

When to Use What

Layout Need	Best Tool
Center one element	Flexbox (shorter)
Navigation bar	Flexbox
Card components	Flexbox (column)
Overall page layout	Grid
Dashboard with panels	Grid
Photo gallery	Grid
Form alignment	Grid (or Flexbox)
Sticky footer	Flexbox
Equal-height columns	Flexbox (`align-items: stretch`)
Complex overlapping	Grid (`grid-area`)
Component that adapts anywhere	Container Query + Grid/Flex

Common Mistakes

/* ❌ Using margin: 0 auto for everything */
.center-old-school {
  width: 80%;
  margin: 0 auto; /* Only works with explicit width */
}

/* ✅ Modern centering */
.center-modern {
  display: flex;
  justify-content: center;
  align-items: center;
}

/* ❌ Float-based layout */
.float-layout::after {
  content: "";
  clear: both;
  display: table;
}
.left { float: left; }
.right { float: right; }

/* ✅ Don't use floats for layout in 2026 */
.flex-layout { display: flex; }
.grid-layout { display: grid; }

/* ❌ Fixed heights */
.sidebar { height: 500px; } /* Breaks on any content change */

/* ✅ Let content determine height */
.sidebar { 
  /* Just let it flow naturally */
  overflow-y: auto; /* Scroll only if needed */
}

/* ❌ Negative margins for positioning */
.bad-positioning { margin-top: -50px; }

/* ✅ Use proper layout tools */
.good-positioning { 
  display: grid;
  grid-row: 1 / 3; /* Overlap properly */
}

Are you team Flexbox, team Grid, or "it depends"?

Follow @armorbreak for more practical web dev guides.

TypeScript Basics: Why and How to Get Started (2026)

Alex Chen — Sat, 23 May 2026 16:35:41 +0000

TypeScript Basics: Why and How to Get Started (2026)

TypeScript isn't just "JavaScript with types." It's a different way of thinking about code.

Why TypeScript in 2026?

The #1 reason I use TypeScript:
Catches bugs BEFORE they reach production.

Real examples from my projects:
→ "Cannot read property 'map' of undefined" → TS catches at compile time
→ Passed string where number expected → TS refuses to compile
→ Misspelled property name → TS tells you immediately
→ Forgot to handle null return → TS warns you

The tradeoff:
+ Fewer runtime bugs
+ Better IDE autocomplete
+ Self-documenting code
- Slightly more verbose
- Build step required
- Learning curve for advanced types

Getting Started

Installation & Setup

# Initialize a new project
npm init -y
npm install typescript --save-dev
npx tsc --init

# Or create an Express + TypeScript project quickly
npm init -y
npm install express
npm install -D typescript @types/express @types/node ts-node nodemon
npx tsc --init

tsconfig.json Essentials

{
  "compilerOptions": {
    "target": "ES2022",                // Output JS version
    "module": "NodeNext",              // Modern module resolution
    "moduleResolution": "NodeNext",
    "outDir": "./dist",                // Compiled output directory
    "rootDir": "./src",               // Source directory
    "strict": true,                   // Enable all strict checks (IMPORTANT!)
    "esModuleInterop": true,          // Interop with CommonJS
    "skipLibCheck": true,             // Skip type checking .d.ts files (faster)
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,              // Generate .d.ts files for libraries
    "sourceMap": true,                // Generate source maps for debugging
    "noUnusedLocals": true,           // Error on unused variables
    "noUnusedParameters": true,       // Error on unused parameters
    "noImplicitReturns": true,        // Error if function might not return value
    "noFallthroughCasesInSwitch": true // Error on switch fallthrough
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

package.json Scripts

{
  "scripts": {
    "build": "tsc",
    "dev": "ts-node-esm src/server.ts",
    "dev:watch": "nodemon --exec ts-node-esm src/server.ts",
    "start": "node dist/server.js",
    "typecheck": "tsc --noEmit"
  }
}

Core Type System

Basic Types

// Primitive types
let isActive: boolean = true;
let count: number = 42;
let name: string = "Alice";
let nothing: null = null;
let notDefined: undefined = undefined;

// bigint and symbol (rarely used but exist)
let bigNum: bigint = 9007199254740991n;
let sym: symbol = Symbol("unique");

// Arrays
const numbers: number[] = [1, 2, 3];
const strings: Array<string> = ["a", "b", "c"];

// Tuples (fixed-length arrays with known types)
let user: [string, number] = ["Alice", 30];
// user = [30, "Alice"]; // ERROR — wrong order!

// Any (avoid when possible!)
let risky: any = "could be anything";
risky = 42;          // No error
risky.foo();         // No error — defeats the purpose of TS!

// Unknown (safer alternative to any)
let safer: unknown = "could be anything";
// safer.foo();       // ERROR — must check type first
if (typeof safer === "string") {
  console.log(safer.toUpperCase()); // OK — narrowed to string
}

// Void (functions that don't return)
function log(message: string): void {
  console.log(message);
  // No return needed
}

// Never (functions that never complete)
function fail(message: string): never {
  throw new Error(message); // Never returns
}

Objects & Interfaces

// Interface — best for object shapes
interface User {
  id: string;
  email: string;
  name: string;
  role: 'user' | 'admin' | 'moderator';
  createdAt: Date;
  updatedAt?: Date;     // Optional field (?)
  readonly internalId: number; // Read-only
}

// Usage
const user: User = {
  id: 'usr_123',
  email: 'alice@example.com',
  name: 'Alice',
  role: 'admin',
  createdAt: new Date(),
  internalId: 9001,
};

// user.internalId = 9999; // ERROR — readonly!
// user.role = 'superadmin'; // ERROR — not in union type!

// Type alias — more flexible than interface
type ID = string;
type Status = 'pending' | 'active' | 'inactive' | 'suspended';
type UserWithStatus = User & { status: Status }; // Intersection

// When to use which:
// → Interface: object shapes, classes implementing them
// → Type alias: unions, intersections, computed types, primitives

Functions

// Full type annotation
function add(a: number, b: number): number {
  return a + b;
}

// Return type inferred (preferred when obvious)
function greet(name: string) {
  return `Hello, ${name}!`; // Inferred as string
}

// Default parameters
function createUser(name: string, role: string = 'user') {
  return { name, role };
}

// Optional parameters
function findUser(id: string, includeDeleted?: boolean) {
  // includeDeleted is boolean | undefined
}

// Rest parameters
function sum(...numbers: number[]): number {
  return numbers.reduce((total, n) => total + n, 0);
}
sum(1, 2, 3, 4, 5); // 15

// Function as type
type FilterFn<T> = (item: T, index: number) => boolean;

function filter<T>(items: T[], predicate: FilterFn<T>): T[] {
  return items.filter(predicate);
}

// Callback typing
function fetchData(
  url: string,
  onSuccess: (data: unknown) => void,
  onError?: (error: Error) => void
): void { /* ... */ }

// Async functions always return Promise<T>
async function getUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return response.json(); // Inferred as Promise<User>
}

Practical Examples

Express Server with TypeScript

import express, { Request, Response, NextFunction } from 'express';
import helmet from 'helmet';
import cors from 'cors';

// Extend Express Request to include custom properties
declare global {
  namespace Express {
    interface Request {
      user?: AuthenticatedUser;
      requestId?: string;
    }
  }
}

interface AuthenticatedUser {
  id: string;
  email: string;
  role: 'user' | 'admin';
}

const app = express();

app.use(helmet());
app.use(cors());
app.use(express.json());

// Typed middleware
function auth(req: Request, _res: Response, next: NextFunction) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    throw new UnauthorizedError('Missing token');
  }

  const payload = verifyToken(header.slice(7));
  req.user = payload; // Works because we extended the Request type
  next();
}

// Typed route handlers
app.get('/api/users/:id', auth, async (req: Request, res: Response) => {
  const user = await userService.findById(req.params.id);
  res.json(user);
});

// Generic API response helper
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
}

function ok<T>(res: Response, data: T, status = 200) {
  return res.status(status).json<ApiResponse<T>>({ success: true, data });
}

function fail(res: Response, code: string, message: string, status = 400) {
  return res.status(status).json<ApiResponse<null>>({
    success: false,
    error: { code, message },
  });
}

// Usage
ok(res, user);                    // infers data type from user
fail(res, 'NOT_FOUND', 'User');   // data is null

Database Models

// Type-safe database operations
interface BaseEntity {
  id: string;
  createdAt: Date;
  updatedAt: Date;
}

interface User extends BaseEntity {
  email: string;
  name: string;
  passwordHash: string;
  role: UserRole;
}

type UserRole = 'user' | 'admin' | 'moderator';

interface CreateUserData {
  email: string;
  name: string;
  password: string;
  role?: UserRole; // defaults to 'user'
}

class UserService {
  async create(data: CreateUserData): Promise<User> {
    const passwordHash = await hashPassword(data.password);

    const user = await db.query(
      'INSERT INTO users (email, name, password_hash, role) VALUES ($1, $2, $3, $4) RETURNING *',
      [data.email, data.name, passwordHash, data.role || 'user']
    );

    return user.rows[0]; // Type-safe access
  }

  async findById(id: string): Promise<User | null> {
    const result = await db.query('SELECT * FROM users WHERE id = $1', [id]);
    return result.rows[0] ?? null; // Proper null handling
  }
}

Utility Types (Built-in)

// Partial<T> — make all fields optional
interface Todo { title: string; done: boolean; priority: number; }
function updateTodo(id: string, updates: Partial<Todo>) {
  // updates can be any subset of Todo fields
}
updateTodo('1', { done: true }); // Only update done field

// Required<T> — make all fields required (inverse of Partial)
// Omit<T, K> — remove specific keys
type TodoInput = Omit<Todo, 'id' | 'createdAt' | 'updatedAt'>;

// Pick<T, K> — keep only specific keys
type TodoPreview = Pick<Todo, 'title' | 'done'>;

// Readonly<T> — make all fields read-only
const config: Readonly<AppConfig> = { ... };

// Record<K, V> — key-value mapping
type RolePermissions = Record<UserRole, string[]>;
const permissions: RolePermissions = {
  admin: ['read', 'write', 'delete'],
  user: ['read'],
  moderator: ['read', 'write'],
};

// Extract type from array
const statuses = ['pending', 'active', 'inactive'] as const;
type Status = typeof statuses[number]; // 'pending' | 'active' | 'inactive'

// Awaited<T> — unwrap Promise type
type UserData = Awaited<ReturnType<typeof userService.findById>>;
// Same as User | null

Error Handling with TypeScript

// Custom error class hierarchy
class AppError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string,
    public details?: unknown
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}

class NotFoundError extends AppError {
  constructor(resource: string) {
    super(404, 'NOT_FOUND', `${resource} not found`);
  }
}

class ValidationError extends AppError {
  constructor(public fields: Array<{ field: string; issue: string }>) {
    super(422, 'VALIDATION_ERROR', 'Validation failed', fields);
  }
}

// Type-narrowing error handler
function isError(error: unknown): error is Error {
  return error instanceof Error;
}

function isAppError(error: unknown): error is AppError {
  return error instanceof AppError;
}

// Safe error handler middleware
function errorHandler(err: unknown, req: Request, res: Response, next: NextFunction) {
  if (isAppError(err)) {
    return res.status(err.statusCode).json({
      error: { code: err.code, message: err.message, details: err.details }
    });
  }

  if (isError(err)) {
    console.error('Unexpected error:', err.stack);
    return res.status(500).json({
      error: { code: 'INTERNAL_ERROR', message: 'An internal error occurred' }
    });
  }

  // Handle non-Error throws (strings, numbers, etc.)
  console.error('Unknown error:', err);
  res.status(500).json({ error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' } });
}

Migration Strategy: JS → TypeScript

Don't rewrite everything at once!

Step 1: Add tsconfig.json with strict: false initially
Step 2: Rename .js files to .ts one by one (start with entry point)
Step 3: Fix errors file by file
Step 4: Enable strict mode gradually:
  → noImplicitAny first
  → strictNullChecks next
  → noUnusedLocals/Params
  → Finally: strict: true

Each file you convert makes your codebase safer.
Even partial TypeScript is better than none.

Quick Reference

Concept	Syntax
Basic annotation	`let x: number = 5`
Array	`number[]` or `Array<number>`
Optional	`field?: string` or `string \
Union	{% raw %}`string \
Literal type	{% raw %}`'success' \
Interface	{% raw %}`interface Name { ... }`
Type alias	`type Name = { ... }`
Generic	`function fn<T>(arg: T): T`
Partial	`Partial<User>`
Omit/Pick	`Omit<User, 'id'>`
Readonly	`Readonly<Config>`
Assert type	`value as string`
Non-null assert	`value!` (use sparingly!)
Satisfies	`const obj = {...} satisfies Shape`

Are you team JavaScript or team TypeScript?

Follow @armorbreak for more practical developer guides.

REST API Security: What Every Developer Must Know (2026)

Alex Chen — Fri, 22 May 2026 18:34:59 +0000

REST API Security: What Every Developer Must Know (2026)

Your API works. Now make sure it doesn't become the next data breach headline.

The Threat Model

Who attacks your API?
→ Bots scraping your data
→ Attackers trying SQL injection
→ Someone brute-forcing passwords
→ Malicious users manipulating other users' data
→ Anyone intercepting traffic (MITM)

Security isn't about eliminating all risk.
It's about making attacks expensive enough that they're not worth it.

1. Authentication & Authorization

Never Roll Your Own Auth

// ❌ NEVER do this
function hashPassword(password) {
  return crypto.createHash('md5').update(password).digest('hex');
}
// MD5 is broken. SHA-1 is broken. Don't hash passwords yourself.

// ✅ Use bcrypt, argon2, or scrypt
const bcrypt = require('bcrypt');
const SALT_ROUNDS = 12;

async function hashPassword(password) {
  return await bcrypt.hash(password, SALT_ROUNDS);
}

async function verifyPassword(password, hash) {
  return await bcrypt.compare(password, hash);
}

// bcrypt is slow by design — that's the point!
// Makes brute-force attacks prohibitively expensive.

JWT Best Practices

const jwt = require('jsonwebtoken');

// Sign with strong secret + short expiry
function generateToken(user) {
  return jwt.sign(
    { 
      id: user.id,
      role: user.role,
      // Don't put sensitive data in JWT payload (it's base64 encoded!)
    },
    process.env.JWT_SECRET,           // At least 32 random chars
    { 
      expiresIn: '15m',               // Short-lived access token
      issuer: 'myapp.com',
      audience: 'myapp-api',
    }
  );
}

// Verify properly
function verifyToken(token) {
  try {
    return jwt.verify(token, process.env.JWT_SECRET, {
      issuer: 'myapp.com',
      audience: 'myapp-api',
    });
  } catch (err) {
    if (err.name === 'TokenExpiredError') throw new UnauthorizedError('Token expired');
    if (err.name === 'JsonWebTokenError') throw new UnauthorizedError('Invalid token');
    throw new UnauthorizedError('Authentication failed');
  }
}

Middleware Pattern

// src/middleware/auth.js
const jwt = require('jsonwebtoken');

function auth(req, res, next) {
  const header = req.headers.authorization;

  if (!header || !header.startsWith('Bearer ')) {
    throw new UnauthorizedError('Missing or invalid authorization header');
  }

  const token = header.split(' ')[1];
  const payload = verifyToken(token);

  req.user = payload; // Attach to request for downstream handlers
  next();
}

// Role-based access
function requireRole(...roles) {
  return (req, res, next) => {
    if (!req.user || !roles.includes(req.user.role)) {
      throw new ForbiddenError(`Requires role: ${roles.join(' or ')}`);
    }
    next();
  };
}

// Usage:
app.get('/api/admin', auth, requireRole('admin'), adminController.dashboard);
app.get('/api/users/me', auth, userController.getProfile);

2. Input Validation

Validate EVERYTHING from the Client

// ❌ Trusting client input
app.get('/api/users/:id', async (req, res) => {
  const user = await db.query(`SELECT * FROM users WHERE id = ${req.params.id}`);
  // SQL INJECTION! User sends "1; DROP TABLE users--"
});

// ✅ Parameterized queries + validation
const { validate } = require('./middleware/validate');

app.get('/api/users/:id',
  validate({ id: [{ type: 'string', pattern: /^[a-f0-9]{24}$/ }] }), // MongoDB ObjectId format
  auth,
  async (req, res) => {
    const user = await db.collection('users').findOne({ 
      _id: new ObjectId(req.params.id) // Safe parameterized query
    });
    if (!user) throw new NotFoundError('User');
    res.json(sanitizeUser(user));
  }
);

// Validate body on write endpoints
app.post('/api/users',
  validate({
    email: [
      { required: true },
      { type: 'email' },
      { maxLength: 255 },
    ],
    name: [
      { required: true },
      { minLength: 2 },
      { maxLength: 100 },
      { pattern: /^[a-zA-Z\s'-]+$/, message: 'Only letters, spaces, hyphens, apostrophes' },
    ],
    password: [
      { required: true },
      { minLength: 8 },
      { custom: (val) => !val.includes(' ') ? null : 'Password cannot contain spaces' },
    ],
  }),
  userController.create
);

Sanitize Output (Don't Leak Data)

// Remove sensitive fields before sending to client
function sanitizeUser(user) {
  const { passwordHash, mfaSecret, recoveryCodes, ...safe } = user;
  return safe;
}

// Also sanitize error messages in production:
// ❌ "Duplicate entry 'user@example.com' for key 'email'" → reveals DB structure
// ✅ "A user with this email already exists"

3. Rate Limiting

// Simple in-memory rate limiter
const rateLimitMap = new Map();

function rateLimit(options = {}) {
  const {
    windowMs = 60_000,     // 1 minute window
    maxRequests = 100,     // Max requests per window
    keyGenerator = (req) => req.ip, // How to identify users
  } = options;

  return (req, res, next) => {
    const key = keyGenerator(req);
    const now = Date.now();

    if (!rateLimitMap.has(key)) {
      rateLimitMap.set(key, { count: 1, resetAt: now + windowMs });
    } else {
      const record = rateLimitMap.get(key);

      if (now > record.resetAt) {
        // Window reset
        record.count = 1;
        record.resetAt = now + windowMs;
      } else {
        record.count++;

        if (record.count > maxRequests) {
          const retryAfterSec = Math.ceil((record.resetAt - now) / 1000);
          res.set('Retry-After', retryAfterSec.toString());
          res.set('X-RateLimit-Limit', maxRequests.toString());
          res.set('X-RateLimit-Remaining', '0');
          res.set('X-RateLimit-Reset', record.resetAt.toString());

          throw new RateLimitError(retryAfterSec);
        }
      }
    }

    next();
  };
}

// Apply globally
app.use(rateLimit({ windowMs: 60_000, maxRequests: 100 }));

// Stricter for auth endpoints (brute-force protection)
app.post('/api/auth/login', 
  rateLimit({ windowMs: 15 * 60_000, maxRequests: 10 }), // 10 attempts per 15 min
  authController.login
);

app.post('/api/auth/register',
  rateLimit({ windowMs: 60 * 60_000, maxRequests: 3 }),   // 3 registrations per hour
  authController.register
);

// Per-user rate limit for API keys
const apiRateLimit = rateLimit({
  windowMs: 60_000,
  maxRequests: 50,
  keyGenerator: (req) => req.user?.id || req.ip,
});

4. HTTPS & Headers

// helmet.js sets security headers automatically
const helmet = require('helmet');
app.use(helmet());

// What helmet sets:
// X-Content-Type-Options: nosniff        → Prevent MIME sniffing
// X-Frame-Options: SAMEORIGIN            → Prevent clickjacking
// X-XSS-Protection: 1; mode=block        → Basic XSS protection
// Referrer-Policy: strict-origin-when-cross-origin → Control referrer info
// Content-Security-Policy: default-src 'self' → Restrict resource loading

// Custom CSP for apps that need external resources
app.use(helmet.contentSecurityPolicy({
  directives: {
    defaultSrc: ["'self'"],
    scriptSrc: ["'self'", "'unsafe-inline'", 'cdn.example.com'],
    styleSrc: ["'self'", "'unsafe-inline'", 'fonts.googleapis.com'],
    fontSrc: ["'self'", 'fonts.gstatic.com'],
    imgSrc: ["'self'", 'data:', 'https:'],
    connectSrc: ["'self'", 'api.example.com'],
  },
}));

// Force HTTPS in production
if (process.env.NODE_ENV === 'production') {
  app.use((req, res, next) => {
    if (req.header('x-forwarded-proto') !== 'https') {
      return res.redirect(301, `https://${req.header('host')}${req.url}`);
    }
    next();
  });
}

5. CORS Configuration

const cors = require('cors');

// ❌ DANGEROUS: Allow everything
app.use(cors()); // Allows ALL origins!

// ✅ Tight configuration
app.use(cors({
  origin: function (origin, callback) {
    const allowedOrigins = [
      'https://myapp.com',
      'https://www.myapp.com',
      'https://staging.myapp.com',
    ];

    // Allow no origin for server-to-server (Postman, curl, etc.)
    if (!origin) return callback(null, true);

    if (allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
  credentials: true,              // Allow cookies/auth headers
  maxAge: 86400,                  // Pre-flight cache for 24h
  optionsSuccessStatus: 204,      // No content for pre-flight
}));

6. Common Vulnerabilities & How to Fix Them

SQL Injection

-- ❌ String concatenation (vulnerable)
SELECT * FROM users WHERE id = '$userId'

-- ✅ Parameterized queries (safe)
SELECT * FROM users WHERE id = ?
-- Or: SELECT * FROM users WHERE id = $1

XSS (Cross-Site Scripting)

// ❌ Rendering raw HTML
res.send(`<div>${userInput}</div>`);

// ✅ Escape output
const escapeHtml = (str) => str
  .replace(/&/g, '&amp;')
  .replace(/</g, '&lt;')
  .replace(/>/g, '&gt;')
  .replace(/"/g, '&quot;')
  .replace(/'/g, '&#39;');
res.send(`<div>${escapeHtml(userInput)}</div>`);

// Better: Use a template engine that auto-escapes (EJS, Pug, Handlebars)
// For APIs returning JSON: XSS risk is lower but still possible via JSONP

CSRF (Cross-Site Request Forgery)

// For cookie-based auth, use CSRF tokens:
const csrf = require('csurf');
app.use(csrf({ cookie: true }));

// Include token in forms and AJAX requests:
app.get('/api/csrf-token', (req, res) => {
  res.json({ csrfToken: req.csrfToken() });
});

// Client must send this token with every mutating request:
fetch('/api/update', {
  method: 'POST',
  headers: { 'X-CSRF-Token': csrfToken, 'Content-Type': 'application/json' },
  body: JSON.stringify(data),
});
// Note: If using JWT (not cookies), CSRF is less of a concern

IDOR (Insecure Direct Object Reference)

// ❌ Anyone can access any user's data
app.get('/api/orders/:id', auth, async (req, res) => {
  const order = await Order.findById(req.params.id); // Any ID!
  res.json(order);
});

// ✅ Enforce ownership
app.get('/api/orders/:id', auth, async (req, res) => {
  const order = await Order.findOne({
    _id: req.params.id,
    userId: req.user.id, // MUST match authenticated user!
  });
  if (!order) throw new NotFoundError('Order');
  res.json(order);
});

Mass Assignment

// ❌ Accept entire body blindly
app.put('/api/users/:id', async (req, res) => {
  const user = await User.findByIdAndUpdate(req.params.id, req.body);
  // Attacker sends { role: 'admin' } → instant admin!
});

// ✅ Whitelist allowed fields
const ALLOWED_UPDATES = ['name', 'email', 'avatar'];

app.put('/api/users/:id', async (req, res) => {
  const updates = {};
  for (const field of ALLOWED_UPDATES) {
    if (req.body[field] !== undefined) {
      updates[field] = req.body[field];
    }
  }
  const user = await User.findByIdAndUpdate(req.params.id, updates);
  res.json(user);
});

7. Logging & Monitoring

// Log security-relevant events
const securityLog = {
  login_success: (req, user) => ({
    event: 'auth.login.success',
    userId: user.id,
    ip: req.ip,
    userAgent: req.headers['user-agent'],
    timestamp: new Date().toISOString(),
  }),

  login_failure: (req, reason) => ({
    event: 'auth.login.failure',
    ip: req.ip,
    reason, // 'bad_password', 'account_locked', etc.
    timestamp: new Date().toISOString(),
  }),

  permission_denied: (req, resource) => ({
    event: 'auth.denied',
    userId: req.user?.id,
    ip: req.ip,
    resource,
    method: req.method,
    path: req.path,
    timestamp: new Date().toISOString(),
  }),

  rate_limit_exceeded: (req) => ({
    event: 'security.rate_limit',
    ip: req.ip,
    path: req.path,
    timestamp: new Date().toISOString(),
  }),
};

// Send alerts for suspicious activity
function checkForAnomalies(logEntry) {
  const ipFailures = countRecentFailures(logEntry.ip);

  if (ipFailures >= 10) {
    alertSecurityTeam({
      level: 'warning',
      type: 'brute_force_attempt',
      ip: logEntry.ip,
      failures: ipFailures,
    });
  }
}

Security Checklist

Before deploying any API:

□ All endpoints require authentication (except public ones)
□ Passwords hashed with bcrypt/argon2 (never plaintext)
□ JWT secrets are ≥ 32 chars and stored in env vars
□ Token expiry is short (≤ 15min for access tokens)
□ All inputs validated AND sanitized
□ Parameterized queries (never string concatenation)
□ Rate limiting on all endpoints (stricter on auth)
□ CORS configured to specific origins only
□ Security headers set (helmet.js)
□ HTTPS enforced in production
□ Ownership checks on all user-scoped resources
□ Field whitelisting on update endpoints
□ No sensitive data in error messages (production)
□ Security logging for auth events
□ Dependencies up to date (npm audit)
□ No secrets in code or git history (.env gitignored)

What's the most important security practice you follow?

Follow @armorbreak for more practical developer guides.

Regular Expressions: The Guide I Always Wanted (2026)

Alex Chen — Fri, 22 May 2026 16:35:31 +0000

Regular Expressions: The Guide I Always Wanted (2026)

Regex doesn't have to be intimidating. Here's how I actually use it day to day.

The Mindset

Regex is a pattern matching language.
It's not code you write once and understand.
It's a tool you build up muscle memory for.

Start with simple patterns.
Use a visualizer (I'll share my favorites).
Gradually add complexity.

You don't need to memorize everything — just know what's possible.

The Essentials

Character Classes

// Literal characters
/abc/.test('abcdef')        // true — exact match
/hello/.test('Hello')       // false — case sensitive!

// Dot = any single character (except newline)
/a.c/.test('abc')           // true
/a.c/.test('aXc')           // true
/a.c/.test('ac')            // false — dot matches exactly one char

// Character classes
/[aeiou]/.test('hello')     // true — contains any vowel
/[0-9]/.test('price: $42')  // true — contains any digit
/[a-zA-Z]/.test('abc123')   // true — contains any letter
/[a-zA-Z0-9_]/.test('var_1') // true — word character (\w)

// Shorthand classes
/\d/.test('42')             // digit [0-9]
/\D/.test('hello')          // non-digit [^0-9]
/\w/.test('hello_123')      // word char [a-zA-Z0-9_]
/\W/.test('!@#$')           // non-word char
/\s/.test('hello world')    // whitespace (space, tab, newline)
/\S/.test('hello')          // non-whitespace

Anchors

/^hello/.test('hello world')  // true — starts with hello
/world$/.test('hello world')  // true — ends with world
/^hello$/.test('hello')       // true — exactly "hello"
/^hello$/.test('hello world') // false

// Word boundaries
/\bword\b/.test('a word here')      // true — standalone word
/\bword\b/.test('swordfish')        // false — not at boundary

Quantifiers

// ? = zero or one
/colou?r/.test('color')   // true
/colou?r/.test('colour')  // true

// * = zero or more
/ab*c/.test('ac')         // true (zero b's)
/ab*c/.test('abbc')       // true (two b's)

// + = one or more
/ab+c/.test('ac')         // false (need at least one b)
/ab+c/.test('abc')        // true

// {n} = exactly n times
/\d{4}/.test('2026')      // true — 4 digits
/\d{4}/.test('26')        // false

// {n,m} = between n and m times
/\d{2,4}/.test('26')      // true
/\d{4,8}/.test('20260523') // true (6 digits)

// Greedy vs Lazy (important!)
/<.+>/.test('<div><p>')   // Matches ENTIRE string (greedy)
/<.+?>/.test('<div><p>')  // Matches only '<div>' (lazy)
// Add ? after quantifier to make it lazy

Practical Examples You'll Actually Use

Email Validation

// Practical (not RFC-compliant, but good enough)
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

emailRegex.test('user@example.com');     // true
emailRegex.test('user.name+tag@domain.co.uk'); // true
emailRegex.test('user@');                // false
emailRegex.test('@example.com');         // false
emailRegex.test('user example.com');     // false (has space)

// Note: For production, use a library like validator.js
// Regex email validation always has edge cases

Password Strength Check

function checkPassword(password) {
  const checks = {
    length: /.{8,}/,
    uppercase: /[A-Z]/,
    lowercase: /[a-z]/,
    digit: /\d/,
    special: /[!@#$%^&*()_+\-=[\]{};':"\\|,.<>\/?]/,
  };

  const results = {};
  let score = 0;

  for (const [name, regex] of Object.entries(checks)) {
    results[name] = regex.test(password);
    if (results[name]) score++;
  }

  return {
    valid: Object.values(results).every(Boolean),
    score: score, // 0-5
    details: results,
    strength: score <= 2 ? 'weak' : score <= 3 ? 'medium' : score === 4 ? 'strong' : 'very strong',
  };
}

checkPassword('password');
// { valid: false, score: 2, strength: 'weak', ... }

checkPassword('P@ssw0rd!');
// { valid: true, score: 5, strength: 'very strong', ... }

URL Parsing

const urlRegex = /^(https?):\/\/([^\/]+)(\/[^\s]*)?$/i;

function parseUrl(url) {
  const match = url.match(urlRegex);
  if (!match) return null;

  return {
    protocol: match[1],
    hostname: match[2],
    path: match[3] || '/',
  };
}

parseUrl('https://dev.to/armorbreak/article');
// { protocol: 'https', hostname: 'dev.to', path: '/armorbreak/article' }

Extract Data from Strings

// Extract numbers from text
const text = 'Order #12345 for $299.99 shipped on 2026-05-23';
const numbers = text.match(/\d+(\.\d+)?/g);
console.log(numbers); // ['12345', '299.99', '2026', '05', '23']

// Extract hashtags
const tweet = 'Learning #regex and #javascript today!';
const hashtags = tweet.match(/#\w+/g);
console.log(hashtags); // ['#regex', '#javascript']

// Extract words in quotes
const str = 'He said "hello world" and left';
const quotes = str.match(/"([^"]*)"/g)?.map(s => s.slice(1, -1));
console.log(quotes); // ['hello world']

// Parse log line format
const logLine = '[2026-05-23 10:30:15] ERROR: Connection failed (code: 503)';
const logPattern = /^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\] (\w+): (.+)/;
const parsed = logLine.match(logPattern);
if (parsed) {
  console.log({ timestamp: parsed[1], level: parsed[2], message: parsed[3] });
}
// { timestamp: '2026-05-23 10:30:15', level: 'ERROR', message: 'Connection failed (code: 503)' }

Search & Replace

// CamelCase to snake_case
function camelToSnake(str) {
  return str.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`);
}
camelToSnake('myVariableName'); // 'my_variable_name'

// snake_case to camelCase
function snakeToCamel(str) {
  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
}
snakeToCamel('my_variable_name'); // 'myVariableName'

// Format phone number
function formatPhone(phone) {
  return phone.replace(/(\d{3})(\d{3})(\d{4})/, '($1) $2-$3');
}
formatPhone('5551234567'); // '(555) 123-4567'

// Remove extra whitespace
'  hello   world  '.replace(/\s+/g, ' ').trim(); // 'hello world'

// Mask credit card
'4111111111111111'.replace(/\d(?=\d{4})/g, '*'); // '************1111'

Groups & Capturing

// Capturing groups — extract parts of the match
const date = 'May 23, 2026';
const datePattern = /(\w+) (\d{1,2}), (\d{4})/;
const match = date.match(datePattern);

match[0]; // "May 23, 2026" (full match)
match[1]; // "Month" (group 1)
match[2]; // "23" (group 2)
match[3]; // "2026" (group 3)

// Named groups (ES2018+, much more readable!)
const dateNamed = /(?<month>\w+) (?<day>\d{1,2}), (?<year>\d{4})/;
const namedMatch = date.exec(date);

namedMatch.groups.month; // "May"
namedMatch.groups.day;   // "23"
namedMatch.groups.year;  // "2026"

// Non-capturing group (?:...) — group without capturing
/(?:https?:\/\/)?(?:www\.)?example\.com/
// Groups exist for grouping but don't appear in results

// Lookahead (assert without consuming)
// Positive lookahead: X(?=Y) — X followed by Y
/\d+(?= dollars)/.test('100 dollars'); // true
// Negative lookahead: X(?!Y) — X NOT followed by Y
/\d+(?! dollars)/.test('100 euros');  // true

// Lookbehind (ES2018+)
// Positive lookbehind: (?<=Y)X — X preceded by Y
/(?<=\$)\d+/.test('$100'); // true
// Negative lookbehind: (?<!Y)X — X NOT preceded by Y
/(?<!\$)\d+/.test('100');  // true (no $ before 100)

Flags

// g — global (find all matches, not just first)
'aaa'.match(/a/g);  // ['a', 'a', 'a']
'aaa'.match(/a/);   // ['a'] (only first)

// i — case insensitive
/HELLO/i.test('hello'); // true

// m — multiline (^ and $ match per-line)
/^line/.test('first\nline two\nthird'); // false
/^line/m.test('first\nline two\nthird'); // true (matches start of line 2)

// s — dotAll (dot matches newlines too)
/.*<end>/.s.test('multi\nline\n<end>'); // true

// Combine flags
/pattern/gims

Common Patterns Library

const patterns = {
  // Validation
  email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
  url: /^https?:\/\/[^\s]+$/i,
  ipV4: /^(\d{1,3}\.){3}\d{1,3}$/,
  hexColor: /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/,
  macAddress: /^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$/,
  uuid: /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$/i,

  // Extraction
  phoneUS: /\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}/,
  hashtag: /#\w+/g,
  mention: /@\w+/g,
  price: /\$\d+(?:\.\d{2})?/g,
  time24h: /(2[0-3]|[01]?[0-9]):([0-5][0-9])/,

  // Code-specific
  semicolonMissing: /[^;{}]\n\s*\n\s*(let|const|var|return|import|export|function)/m,
  consoleLog: /console\.(log|debug|info|warn|error)/,
  todoComment: /\/\/\s*TODO[:\s]|#\s*TODO[:\s]/i,
};

// Usage
patterns.email.validate = (str) => patterns.email.test(str);
patterns.price.extract = (str) => str.match(patterns.price.g || patterns.price) || [];

Testing & Debugging Regex

// Use Node.js built-in test
const regex = /pattern/;
regex.test('string');  // boolean
string.match(regex);   // array or null
string.replace(regex, 'replacement');
string.split(regex);   // array
string.search(regex);  // index or -1

// Test multiple cases quickly
const testCases = [
  ['user@example.com', true],
  ['', false],
  ['invalid', false],
  ['@no-user.com', false],
];

for (const [input, expected] of testCases) {
  const result = patterns.email.test(input);
  const status = result === expected ? '✅' : '❌';
  console.log(`${status} "${input}" → ${result}`);
}

// Online tools I use:
// → regex101.com (best overall, explains each part)
// → regexr.com (great visual highlighting)
// → debuggex.com (interactive railroad diagram)

Performance Tips

// ❌ Catastrophic backtracking (can freeze your app!)
// This can take exponential time on certain inputs:
 /^(a+)+$/.test('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaX');

// ✅ Use possessive quantifiers or atomic groups when possible
// Or restructure the pattern to avoid nested quantifiers

// ❌ Slow: Compiling regex in loops
for (const item of items) {
  const match = item.match(/pattern/); // Recompiles every iteration!
}

// ✅ Fast: Compile once, reuse
const pattern = /pattern/;
for (const item of items) {
  const match = item.match(pattern); // Uses compiled version
}

// ⚠️ Be careful with .match() and global flag
'aaa'.match(/a/g); // ['a', 'a', 'a']
'bbb'.match(/a/g); // null (not empty array!)
// Always null-check or use ?? []

Quick Reference

Pattern	Meaning
`.`	Any char except newline
`\d`, `\D`	Digit / Non-digit
`\w`, `\W`	Word char / Non-word
`\s`, `\S`	Whitespace / Non-whitespace
`^`, `$`	Start / End of string
`\b`	Word boundary
`*`, `+`, `?`	0+, 1+, 0/1
`{n}`, `{n,m}`	Exact / Range count
`(…)`	Capture group
`(?:…)`	Non-capturing group
`(?<name>…)`	Named group
`(?=…)`, `(?!…)`	Lookahead
`(?<=…)`, `(?<!…)`	Lookbehind
`\1`, `\2`	Backreference to group
`g`, `i`, `m`, `s`	Flags

What's your most-used regex pattern?

Follow @armorbreak for more practical developer guides.

Git Advanced: The Commands I Wish I Knew Earlier (2026)

Alex Chen — Thu, 21 May 2026 22:34:57 +0000

Git Advanced: The Commands I Wish I Knew Earlier (2026)

Beyond add, commit, push. These are the Git commands that actually save time.

The Basics (Quick Refresher)

git status          # What changed?
git diff             # What exactly changed?
git log --oneline   # Recent commits
git add -A           # Stage everything
git commit -m "msg"  # Commit staged changes
git push origin main # Send to remote

You know these. Let's go further.

Undo Everything (Safely)

# Unstage a file (keep changes)
git reset HEAD path/to/file

# Discard all unstaged changes in a file
git checkout -- path/to/file
# Or newer syntax:
git restore path/to/file

# Discard ALL unstaged changes
git checkout -- .
git restore .

# Uncommit (keep changes, remove commit)
git reset --soft HEAD~1    # Changes stay staged
git reset HEAD~1           # Changes stay unstaged
git reset --hard HEAD~1    # Changes GONE forever ⚠️

# Amend last commit (fix message or add forgotten file)
git commit --amend -m "Better message"
git add forgotten-file.txt
git commit --amend         # Add file to previous commit

Interactive Rebase: Clean Up History

# Edit/reorder/squash last 5 commits
git rebase -i HEAD~5

# Opens editor with:
pick abc1234 First commit
pick def5678 Second commit
pick ghi9012 Third commit
pick jkl3456 Fourth commit
pick mno7890 Fifth commit

# Change 'pick' to:
# reword  = edit commit message
# edit    = pause to amend files
# squash  = merge into previous commit
# fixup   = merge into previous (discard this message)
# drop    = remove commit entirely
# exec    = run shell command

# Example: Squash the last 2 commits into one
pick abc1234 First commit
squash def5678 Second commit
# → Creates single commit with combined changes

Stashing: Save Work Without Committing

# Save current work temporarily
git stash
git stash push -m "WIP: feature X"

# List all stashes
git stash list
# stash@{0}: On main: WIP: feature X
# stash@{1}: On main: bugfix attempt

# Restore most recent stash
git stash pop      # Apply + remove from list
git stash apply    # Apply + keep in list

# Restore specific stash
git stash apply stash@{1}

# Drop a stash
git stash drop stash@{0}

# Clear all stashes
git stash clear

# Stash only some files (not everything)
git stash push -m "partial" src/utils.js src/config.js

# Stash with untracked files included
git stash push -u -m "include new files"

Searching Through History

# Search commit messages
git log --grep="bug fix" --oneline
git log --grep="auth" --since="2026-01-01"

# Search code content across all history
git log -S "functionName" --oneline     # Added/removed this string
git log -G "pattern" --oneline          # Changed matching this regex
git log -p -S "TODO"                    # Show actual diffs too

# Find which commit introduced a bug
git bisect start
git bisect bad                          # Current version has bug
git bisect good v1.0.0                  # This version was fine
# Git will check out middle commit → you test → mark good/bad
# Repeat until it finds the exact bad commit
git bisect reset                        # When done

# Search current working tree
git grep "search term"                  # In tracked files
git grep "search term" $(git rev-list --all)  # Across ALL history!

Branching Strategies That Work

Feature Branch Workflow

# Start a new feature
git checkout -b feature/user-auth
# Or:
git switch -c feature/user-auth

# Make commits...
git add -A && git commit -m "Add login page"

# Update your branch with latest main
git fetch origin
git rebase origin/main        # Cleaner than merge for PRs

# Push branch (first time needs -u)
git push -u origin feature/user-auth

# After PR is merged, clean up
git branch -d feature/user-auth              # Delete local
git push origin --delete feature/user-auth   # Delete remote

Quick Branch Management

# See all branches (local + remote)
git branch -a

# Rename current branch
git branch -m old-name new-name

# Rename remote branch (after local rename)
git push origin :old-name new-name

# Switch to previous branch
git checkout -
# Or: git switch -

# Compare branches
git log main..feature-branch --oneline    # Commits in feature but not main
git diff main...feature-branch            # Diff between branch tips

# Merge vs Rebase summary:
# git merge feature   → Creates merge commit, preserves exact history
# git rebase feature  → Linear history, rewrites commits (cleaner for PRs)

Dealing with Remote Changes

# Fetch all remotes (doesn't merge)
git fetch --all

# Pull = fetch + merge
git pull origin main

# Pull with rebase (avoids extra merge commits)
git pull --rebase origin main

# Force push (⚠️ dangerous on shared branches!)
git push --force-with-lease origin feature-branch
# Safer than --force: checks if remote changed first

# Remove remote tracking branch that was deleted
git prune
git fetch --prune                         # Fetch + cleanup stale refs

Cherry-Picking: Grab Specific Commits

# Apply one commit from another branch
git cherry-pick abc1234

# Apply multiple commits
git cherry-pick abc1234 def5678 ghi9012

# Cherry-pick without committing (edit first)
git cherry-pick -n abc1234
# Make changes, then:
git commit -m "Modified cherry-pick"

# Cherry-pick from another repo (as patch)
git format-patch -1 abc1234 --stdout > /tmp/patch.git
git am < /tmp/patch.git

Fixing Mistakes in Committed Code

# Forgot to include a file in last commit?
git add forgotten-file.js
git commit --amend --no-edit

# Need to change an older commit? Use interactive rebase:
git rebase -i HEAD~5
# Change 'pick' to 'edit' on the target commit
# Make your changes
git add fixed-file.js
git rebase --continue

# Split a commit into two:
git rebase -i HEAD~3
# Change 'pick' to 'edit' on target commit
git reset HEAD~1                # Uncommit while keeping changes
git add file-a.js               # Stage part of changes
git commit -m "Part A: file A"
git add file-b.js               # Stage rest
git commit -m "Part B: file B"
git rebase --continue

Understanding .gitignore

# Patterns
node_modules/                   # Directory
*.log                           # All .log files
!.important.log                 # Except this one
build/                          # Build output
.env                            # Secrets (NEVER commit!)
.DS_Store                       # macOS junk
.vscode/                        # Editor config (optional)

# Global ignore (for all repos)
git config --global core.excludesfile ~/.gitignore_global

# Debug what's being ignored
git check-ignore -v node_modules/debug.log
git status --ignored            # Show ignored files too

# Track a file that's already .gitignored
git add -f important.log        # Force add (-f overrides ignore rules)

# Stop tracking a file (but keep locally)
git rm --cached large-file.dat
# Then add to .gitignore

Useful Aliases

# Save typing with aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --graph --oneline --decorate -20"
git config --global alias.unstage "reset HEAD --"
git config --global alias.last "log -1 --stat"
git config --global alias.amend "commit --amend --no-edit"
git config --global alias.cleanup "!git branch --merged | grep -v '\\*\\|main\\|develop' | xargs git branch -d"
git config --global alias.discard "checkout --"

# Now use:
git co feature-branch       # = git checkout
git lg                      # Beautiful graph log
git cleanup                 # Delete merged branches
git discard filename        # Discard changes to file

Quick Reference Card

Task	Command
Undo last commit (keep files)	`git reset --soft HEAD~1`
Undo last commit (lose files)	`git reset --hard HEAD~1`
Amend last commit	`git commit --amend`
Save work temporarily	`git stash` / `git stash pop`
Edit recent commits	`git rebase -i HEAD~N`
Find commit that added text	`git log -S "text"`
Compare branches	`git diff main...feature`
Clean merged branches	`git branch --merged \
Safe force push	{% raw %}`git push --force-with-lease`
Grab commit from other branch	`git cherry-pick <sha>`
Bisect to find bug commit	`git bisect start/good/bad/reset`

Which Git command saved you the most time?

Follow @armorbreak for more practical developer guides.

SQL Basics Every Developer Should Know (2026)

Alex Chen — Thu, 21 May 2026 16:35:03 +0000

SQL Basics Every Developer Should Know (2026)

You don't need to be a DBA, but you do need to write queries that don't suck.

Why SQL Still Matters in 2026

ORMs are great for CRUD.
But when things get complex:
→ ORM generates terrible queries
→ You need joins, aggregations, window functions
→ Performance debugging requires reading actual SQL
→ The database is usually your bottleneck

Learn SQL once, use it everywhere.
Every "NoSQL" database eventually adds SQL-like querying.

The Essential Queries

SELECT: Read Data

-- Basic
SELECT * FROM users;

-- Specific columns (always prefer this over *)
SELECT id, email, name FROM users;

-- With alias
SELECT 
  u.id AS user_id,
  u.email,
  COUNT(o.id) AS order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id;

WHERE: Filter Data

-- Basic conditions
SELECT * FROM users WHERE active = true;
SELECT * FROM products WHERE price > 100;

-- Multiple conditions
SELECT * FROM orders 
WHERE status = 'completed' 
  AND created_at >= '2026-01-01'
  AND total_amount > 50;

-- Pattern matching
SELECT * FROM users WHERE email LIKE '%@gmail.com';
SELECT * FROM users WHERE name LIKE 'J%';       -- Starts with J
SELECT * FROM users WHERE phone LIKE '555-____'; -- Wildcard for digits

-- IN clause (cleaner than multiple OR)
SELECT * FROM users WHERE role IN ('admin', 'moderator');

-- NULL handling (⚠️ NULL != NULL)
SELECT * FROM users WHERE email IS NOT NULL;
SELECT * FROM products WHERE description IS NULL OR description = '';

-- BETWEEN (inclusive)
SELECT * FROM orders WHERE created_at BETWEEN '2026-01-01' AND '2026-03-31';

JOINs: Combine Tables

-- INNER JOIN: Only matching rows
SELECT u.name, o.total_amount
FROM users u
INNER JOIN orders o ON u.id = o.user_id;

-- LEFT JOIN: All from left, matching from right (NULL if no match)
SELECT u.name, COUNT(o.id) AS order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id;

-- Multiple JOINs
SELECT 
  u.name,
  p.name AS product_name,
  oi.quantity,
  oi.unit_price
FROM users u
JOIN orders o ON u.id = o.user_id
JOIN order_items oi ON o.id = oi.order_id
JOIN products p ON oi.product_id = p.id
WHERE u.id = 123;

ORDER BY + LIMIT: Sort & Paginate

-- Basic sorting
SELECT * FROM products ORDER BY price ASC;
SELECT * FROM products ORDER BY created_at DESC;

-- Multi-column sort
SELECT * FROM users ORDER BY last_login DESC, name ASC;

-- Pagination (crucial!)
-- Page 1 (items 1-20):
SELECT * FROM products ORDER BY created_at DESC LIMIT 20 OFFSET 0;

-- Page 2 (items 21-40):
SELECT * FROM products ORDER BY created_at DESC LIMIT 20 OFFSET 20;

-- Page N:
SELECT * FROM products ORDER BY created_at DESC LIMIT 20 OFFSET ((N - 1) * 20);

Aggregations & Grouping

-- Basic aggregates
SELECT 
  COUNT(*) AS total_orders,
  SUM(total_amount) AS revenue,
  AVG(total_amount) AS avg_order_value,
  MIN(total_amount) AS min_order,
  MAX(total_amount) AS max_order
FROM orders 
WHERE status = 'completed';

-- GROUP BY with HAVING
SELECT 
  status,
  COUNT(*) AS count,
  SUM(total_amount) AS revenue
FROM orders
GROUP BY status
HAVING COUNT(*) > 10;  -- Filter AFTER grouping (unlike WHERE)

-- Common pattern: Top N per category
SELECT 
  category,
  product_name,
  sales_count
FROM (
  SELECT 
    c.name AS category,
    p.name AS product_name,
    SUM(oi.quantity) AS sales_count,
    ROW_NUMBER() OVER (PARTITION BY c.id ORDER BY SUM(oi.quantity) DESC) AS rank
  FROM categories c
  JOIN products p ON c.id = p.category_id
  JOIN order_items oi ON p.id = oi.product_id
  GROUP BY c.id, p.id
) ranked
WHERE rank <= 3;  -- Top 3 products per category

INSERT, UPDATE, DELETE

-- Insert single row
INSERT INTO users (email, name, role) VALUES ('test@example.com', 'Test User', 'user');

-- Insert multiple rows (faster than individual inserts)
INSERT INTO products (name, price, category_id) VALUES
  ('Widget A', 29.99, 1),
  ('Widget B', 49.99, 1),
  ('Gadget C', 99.99, 2);

-- Upsert (insert or update if exists)
INSERT INTO user_settings (user_id, theme, notifications)
VALUES (123, 'dark', true)
ON CONFLICT (user_id) DO UPDATE SET
  theme = EXCLUDED.theme,
  notifications = EXCLUDED.notifications;

-- Update
UPDATE products SET price = 34.99 WHERE id = 42;

-- Conditional update
UPDATE users SET 
  login_count = login_count + 1,
  last_login = NOW()
WHERE id = 123;

-- Delete (use with caution!)
DELETE FROM sessions WHERE expires_at < NOW();

-- Soft delete (preferred in production)
UPDATE users SET deleted_at = NOW(), active = false WHERE id = 123;

Subqueries vs CTEs

-- Subquery (harder to read)
SELECT * FROM products 
WHERE price > (SELECT AVG(price) FROM products);

-- CTE — same thing, much clearer
WITH avg_price AS (
  SELECT AVG(price) AS value FROM products
)
SELECT * FROM products, avg_price
WHERE products.price > avg_price.value;

-- Complex example using CTEs
WITH monthly_revenue AS (
  SELECT 
    DATE_TRUNC('month', created_at) AS month,
    SUM(total_amount) AS revenue
  FROM orders
  WHERE status = 'completed'
  GROUP BY month
),
monthly_target AS (
  SELECT 
    month,
    LAG(revenue) OVER (ORDER BY month) AS prev_month_revenue,
    revenue - LAG(revenue) OVER (ORDER BY month) AS growth
  FROM monthly_revenue
)
SELECT 
  month::text,
  revenue,
  prev_month_revenue,
  ROUND((growth / prev_month_revenue * 100), 1) || '%' AS growth_pct
FROM monthly_target
ORDER BY month;

Indexing Essentials

-- Create index (basic)
CREATE INDEX idx_users_email ON users(email);

-- Composite index (order matters!)
CREATE INDEX idx_orders_user_date ON orders(user_id, created_at DESC);

-- Unique index (also enforces uniqueness)
CREATE UNIQUE INDEX idx_users_email_unique ON users(email);

-- Partial index (index only a subset of rows)
CREATE INDEX idx_active_users ON users(id) WHERE active = true;

-- Check what indexes exist
\di table_name   -- In psql
-- Or:
SELECT indexname, indexdef FROM pg_indexes WHERE tablename = 'users';

-- When to add an index:
-- → WHERE clause columns used frequently
-- → JOIN columns (foreign keys)
-- → Columns in ORDER BY combined with WHERE
-- → Columns with high cardinality (many unique values)

-- When NOT to add an index:
-- → Small tables (< 100 rows)
-- → Columns rarely queried
-- → Columns with low cardinality (e.g., boolean flags)
-- → Tables that are written much more than read

Performance Anti-Patterns

-- ❌ SELECT * (wastes bandwidth, prevents index-only scans)
SELECT * FROM users WHERE email = 'x';

-- ✅ Select only needed columns
SELECT id, name, email FROM users WHERE email = 'x';

-- ❌ N+1 problem (1 query for list + N queries for each item)
-- First query gets 100 users
-- Then loop: SELECT * FROM orders WHERE user_id = ? (100 more queries!)

-- ✅ Use JOIN instead
SELECT u.*, COUNT(o.id) AS order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id;

-- ❌ Missing WHERE clause on large tables
SELECT COUNT(*) FROM events; -- Scans millions of rows

-- ✅ Always filter
SELECT COUNT(*) FROM events WHERE created_at >= NOW() - INTERVAL '30 days';

-- ❌ LIKE '%term' (can't use index — leading wildcard)
SELECT * FROM products WHERE name '%widget';

-- ✅ Use full-text search or trigram index instead
SELECT * FROM products WHERE name ILIKE 'widget%'; -- Leading literal can use index

-- ❌ ORDER BY RAND() (slow on large tables)
SELECT * FROM products ORDER BY RANDOM() LIMIT 5;

-- ✅ Alternative approaches
-- For sequential IDs: random ID range then LIMIT
SELECT * FROM products 
WHERE id >= (RANDOM() * (SELECT MAX(id) FROM products))
LIMIT 5;

-- ❌ No LIMIT on unbounded queries
SELECT * FROM logs; -- Returns ALL rows

-- ✅ Always paginate
SELECT * FROM logs ORDER BY created_at DESC LIMIT 100 OFFSET 0;

Transactions

BEGIN;

-- Transfer money between accounts
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;

INSERT INTO transactions (from_account, to_account, amount)
VALUES (1, 2, 100);

COMMIT;  -- Both updates apply atomically

-- If something goes wrong:
ROLLBACK;  -- Everything reverts

In Node.js:

const client = await pool.connect();
try {
  await client.query('BEGIN');

  await client.query('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [100, fromId]);
  await client.query('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [100, toId]);

  await client.query('COMMIT');
} catch (err) {
  await client.query('ROLLBACK');
  throw err;
} finally {
  client.release();
}

Quick Reference

Task	Syntax
Get all	`SELECT * FROM t`
Filter	`WHERE col = val`
Pattern match	`WHERE col LIKE '%term'`
Combine tables	`FROM a JOIN b ON a.id = b.a_id`
Group & aggregate	`GROUP BY col HAVING condition`
Sort	`ORDER BY col DESC`
Paginate	`LIMIT n OFFSET m`
Insert row	`INSERT INTO t (cols) VALUES (vals)`
Update	`UPDATE t SET col = val WHERE cond`
Delete	`DELETE FROM t WHERE cond`
Aggregate functions	`COUNT(), SUM(), AVG(), MIN(), MAX()`
Combine results	`UNION` (dedupes) / `UNION ALL` (keeps all)
Check existence	`EXISTS (subquery)` or `IN (...)`
Null coalesce	`COALESCE(col, default)`

What's your SQL level? Comfortable with basics or diving into query optimization?

Follow @armorbreak for more practical developer guides.

Error Handling in Node.js: Beyond Try/Catch (2026)

Alex Chen — Thu, 21 May 2026 00:35:26 +0000

Error Handling in Node.js: Beyond Try/Catch (2026)

Most developers stop at try/catch. Here's the complete error handling system I use in production.

The Problem with Basic Error Handling

// ❌ This is what most code looks like
app.get('/api/users/:id', async (req, res) => {
  try {
    const user = await User.findById(req.params.id);
    res.json(user);
  } catch (err) {
    console.error(err); // Lost in a sea of logs
    res.status(500).json({ error: 'Something went wrong' }); // Useless message
  }
});

// Problems:
// 1. No error classification — everything is "something went wrong"
// 2. No context — which user? Which request?
// 3. No recovery strategy — can the client retry?
// 4. Leaks internals in development, hides them in production inconsistently

Step 1: Custom Error Classes

// src/errors/AppError.js
class AppError extends Error {
  constructor(message, statusCode = 500, code = 'INTERNAL_ERROR') {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = statusCode;
    this.code = code;           // Machine-readable error code
    this.isOperational = true;  // Distinguishes from programming errors
    Error.captureStackTrace(this, this.constructor);
  }

  toJSON() {
    return {
      error: {
        code: this.code,
        message: this.message,
        ...(this.details && { details: this.details }),
        ...(this.field && { field: this.field }),
      }
    };
  }
}

// Predefined error types
class NotFoundError extends AppError {
  constructor(resource = 'Resource', id) {
    super(`${resource} not found${id ? ` (id: ${id})` : ''}`, 404, 'NOT_FOUND');
    this.resource = resource;
  }
}

class ValidationError extends AppError {
  constructor(details = []) {
    super('Validation failed', 422, 'VALIDATION_ERROR');
    this.details = details;     // Array of { field, issue }
  }
}

class UnauthorizedError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 401, 'UNAUTHORIZED');
  }
}

class ForbiddenError extends AppError {
  constructor(message = 'Access denied') {
    super(message, 403, 'FORBIDDEN');
  }
}

class ConflictError extends AppError {
  constructor(resource, field) {
    super(
      `${resource} already exists`,
      409,
      'CONFLICT'
    );
    this.resource = resource;
    this.field = field;
  }
}

class RateLimitError extends AppError {
  constructor(retryAfterSeconds = 60) {
    super('Too many requests', 429, 'RATE_LIMITED');
    this.retryAfter = retryAfterSeconds;
  }
}

module.exports = {
  AppError,
  NotFoundError,
  ValidationError,
  UnauthorizedError,
  ForbiddenError,
  ConflictError,
  RateLimitError,
};

Step 2: Centralized Error Handler Middleware

// src/middleware/errorHandler.js
const { AppError } = require('../errors');

function errorHandler(err, req, res, _next) {
  const requestId = req.id || req.headers['x-request-id'];

  // Default values for unexpected errors
  let statusCode = err.statusCode || 500;
  let errorCode = err.code || 'INTERNAL_ERROR';
  let message = err.message || 'An internal error occurred';

  // Log ALL errors with context
  const logData = {
    requestId,
    method: req.method,
    path: req.path,
    ip: req.ip,
    userId: req.user?.id,
    errorName: err.name,
    errorMessage: message,
    errorCode,
    statusCode,
    stack: err.stack,
  };

  if (err.isOperational) {
    // Expected business logic error → info level
    console.info(JSON.stringify(logData));
  } else {
    // Unexpected/programming error → error + alert
    console.error(JSON.stringify(logData));

    // In production, don't leak internals
    if (process.env.NODE_ENV === 'production') {
      statusCode = 500;
      errorCode = 'INTERNAL_ERROR';
      message = 'An internal error occurred';

      // TODO: Send to Sentry/DataDog/etc here
      // captureException(err, { requestId });
    }
  }

  // Build response
  const response = {
    error: {
      code: errorCode,
      message,
    },
  };

  // Include request ID for support lookup
  if (requestId) {
    response.requestId = requestId;
  }

  // Include retry info for rate limits / service unavailable
  if (err.retryAfter) {
    response.retryAfter = err.retryAfter;
  }

  // Include details for validation errors
  if (err.details) {
    response.error.details = err.details;
  }

  // Send response
  res.status(statusCode).json(response);
}

// Handle unhandled promise rejections
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', JSON.stringify({
    reason: reason?.message || String(reason),
    stack: reason?.stack,
  }));

  // Don't crash in production, but do in test
  if (process.env.NODE_ENV === 'test') {
    throw reason;
  }
});

// Handle uncaught exceptions (last resort)
process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', JSON.stringify({
    message: err.message,
    stack: err.stack,
  }));

  // Unrecoverable — must exit
  // Use a graceful shutdown instead of process.exit(1)
  gracefulShutdown('UNCAUGHT_EXCEPTION');
});

module.exports = errorHandler;

Step 3: Using It in Controllers

// src/controllers/userController.js
const { NotFoundError, ValidationError, ConflictError } = require('../errors');
const userService = require('../services/userService');

exports.getUser = async (req, res, next) => {
  try {
    const user = await userService.findById(req.params.id);
    if (!user) throw new NotFoundError('User', req.params.id);
    res.json({ data: user });
  } catch (err) {
    next(err); // Pass to centralized handler
  }
};

exports.createUser = async (req, res, next) => {
  try {
    const { email, name, password } = req.body;

    // Validation
    const errors = [];
    if (!email) errors.push({ field: 'email', issue: 'Email is required' });
    if (!name) errors.push({ field: 'name', issue: 'Name is required' });
    if (!password) errors.push({ field: 'password', issue: 'Password is required' });
    else if (password.length < 8) errors.push({ field: 'password', issue: 'Must be 8+ characters' });

    if (errors.length > 0) throw new ValidationError(errors);

    // Business rule check
    const existing = await userService.findByEmail(email);
    if (existing) throw new ConflictError('User', 'email');

    const user = await userService.create({ email, name, password });
    res.status(201).json({ data: user });
  } catch (err) {
    next(err);
  }
};

Step 4: Async Wrapper (Eliminates Try/Catch Boilerplate)

// src/middleware/asyncHandler.js
// Wraps async route handlers to forward errors to Express error middleware

const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

module.exports = asyncHandler;

Now your controllers become clean:

// BEFORE (verbose):
exports.getUser = async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) throw new NotFoundError('User');
    res.json(user);
  } catch (err) {
    next(err);
  }
};

// AFTER (clean):
exports.getUser = asyncHandler(async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) throw new NotFoundError('User');
  res.json(user);
});

Step 5: Input Validation Middleware

// src/middleware/validate.js
const { ValidationError } = require('../errors');

// Validation rules schema
function validate(rules) {
  return (req, res, next) => {
    const errors = [];
    const source = { ...req.body, ...req.query, ...req.params };

    for (const [field, fieldRules] of Object.entries(rules)) {
      const value = source[field];

      for (const rule of fieldRules) {
        if (rule.required && (value === undefined || value === null)) {
          errors.push({ field, issue: `${field} is required` });
          break; // Skip other rules for missing fields
        }

        if (value === undefined || value === null) continue; // Optional field not provided

        if (rule.type === 'string' && typeof value !== 'string') {
          errors.push({ field, issue: `Must be a string` });
        } else if (rule.type === 'number' && typeof value !== 'number') {
          errors.push({ field, issue: `Must be a number` });
        } else if (rule.type === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
          errors.push({ field, issue: `Invalid email format` });
        } else if (rule.minLength && typeof value === 'string' && value.length < rule.minLength) {
          errors.push({ field, issue: `Must be at least ${rule.minLength} characters` });
        } else if (rule.maxLength && typeof value === 'string' && value.length > rule.maxLength) {
          errors.push({ field, issue: `Must be no more than ${rule.maxLength} characters` });
        } else if (rule.min !== undefined && typeof value === 'number' && value < rule.min) {
          errors.push({ field, issue: `Must be >= ${rule.min}` });
        } else if (rule.max !== undefined && typeof value === 'number' && value > rule.max) {
          errors.push({ field, issue: `Must be <= ${rule.max}` });
        } else if (rule.enum && !rule.enum.includes(value)) {
          errors.push({ field, issue: `Must be one of: ${rule.enum.join(', ')}` });
        } else if (rule.pattern && !rule.pattern.test(value)) {
          errors.push({ field, issue: `Invalid format` });
        } else if (rule.custom && typeof rule.custom === 'function') {
          const customError = rule.custom(value, source);
          if (customError) errors.push({ field, issue: customError });
        }
      }
    }

    if (errors.length > 0) {
      return next(new ValidationError(errors));
    }

    next();
  };
}

// Usage:
app.post('/api/users',
  validate({
    email: [
      { type: 'email', required: true },
      { maxLength: 255 },
    ],
    name: [
      { type: 'string', required: true },
      { minLength: 2 },
      { maxLength: 100 },
    ],
    password: [
      { type: 'string', required: true },
      { minLength: 8 },
      { pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, message: 'Must contain uppercase, lowercase, and number' },
    ],
    role: [
      { enum: ['user', 'admin'] }, // optional, defaults if not sent
    ],
  }),
  userController.createUser
);

Step 6: API Response Standardization

// src/utils/response.js

class ApiResponse {
  static success(res, data, meta = {}) {
    return res.status(200).json({
      success: true,
      data,
      ...meta,
    });
  }

  static created(res, data) {
    return res.status(201).json({
      success: true,
      data,
    });
  }

  static noContent(res) {
    return res.status(204).send();
  }

  static paginated(res, items, page, limit, total) {
    return res.status(200).json({
      success: true,
      data: items,
      pagination: {
        page: Number(page),
        limit: Number(limit),
        total,
        totalPages: Math.ceil(total / limit),
        hasNext: page * limit < total,
        hasPrev: page > 1,
      },
    });
  }

  static error(res, error) {
    return res.status(error.statusCode || 500).json(error.toJSON());
  }
}

module.exports = ApiResponse;

What the Client Sees

Success Response

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Paginated Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": true
  }
}

Error Responses

// Not Found
{ "error": { "code": "NOT_FOUND", "message": "User not found (id: xyz)" } }

// Validation Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "email", "issue": "Invalid email format" },
      { "field": "password", "issue": "Must be 8+ characters" }
    ]
  }
}

// Internal Error (with request ID for support)
{
  "error": { "code": "INTERNAL_ERROR", "message": "An internal error occurred" },
  "requestId": "req_abc123"
}

Graceful Shutdown

let isShuttingDown = false;

function gracefulShutdown(reason = 'SIGTERM') {
  if (isShuttingDown) return;
  isShuttingDown = true;

  console.log(`\n[${reason}] Starting graceful shutdown...`);

  // Stop accepting new connections
  server.close(() => {
    console.log('[shutdown] HTTP server closed');
    process.exit(0);
  });

  // Force exit after timeout (e.g., 10 seconds)
  setTimeout(() => {
    console.error('[shutdown] Forced exit after timeout');
    process.exit(1);
  }, 10_000);
}

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));

Testing Your Error Handling

// tests/unit/errors.test.js
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { NotFoundError, ValidationError, AppError } from '../src/errors/index.js';

describe('NotFoundError', () => {
  it('should have correct status code and message', () => {
    const err = new NotFoundError('User', '123');
    assert.equal(err.statusCode, 404);
    assert.equal(err.code, 'NOT_FOUND');
    assert.equal(err.message, 'User not found (id: 123)');
    assert.equal(err.isOperational, true);
  });

  it('should serialize to JSON correctly', () => {
    const err = new NotFoundError('Post');
    const json = err.toJSON();
    assert.equal(json.error.code, 'NOT_FOUND');
    assert.ok(json.error.message.includes('Post'));
  });
});

describe('ValidationError', () => {
  it('should include details array', () => {
    const err = new ValidationError([
      { field: 'email', issue: 'Required' },
      { field: 'name', issue: 'Required' },
    ]);
    assert.equal(err.statusCode, 422);
    assert.equal(err.details.length, 2);
  });
});

How do you handle errors? Still using basic try/catch or have you built something more robust?

Follow @armorbreak for more practical Node.js guides.

JavaScript Number Tricks Every Developer Should Know (2026)

Alex Chen — Wed, 20 May 2026 18:36:07 +0000

JavaScript Number Tricks Every Developer Should Know (2026)

Numbers in JavaScript are weirder than you think. Here are the tricks that save me from bugs.

The Big Gotcha: Floating Point

0.1 + 0.2 === 0.3    // false!
0.1 + 0.2            // 0.30000000000000004

This isn't a JavaScript bug — it's how IEEE 754 floating point works.

Fix #1: Comparing Numbers

// ❌ Never use == or === for floats
if (a === b) { ... }     // Dangerous!

// ✅ Use epsilon comparison
function approxEqual(a, b, epsilon = Number.EPSILON) {
  return Math.abs(a - b) < epsilon;
}

approxEqual(0.1 + 0.2, 0.3)   // true

Fix #2: Currency (Never Use Floats!)

// ❌ WRONG
const price = 19.99;
const tax = price * 0.088;      // 1.7591200000000002
const total = price + tax;     // 21.7491200000000002

// ✅ Option A: Work in cents (integers)
const priceCents = 1999;
const taxCents = Math.round(priceCents * 88 / 1000); // 176
const totalCents = priceCents + taxCents; // 2175
console.log((totalCents / 100).toFixed(2)); // "21.75"

// ✅ Option B: Round at display time
const total = parseFloat((price * 1.088).toFixed(2)); // "21.75"

// ✅ Option C: Use a library (for serious financial apps)
// intl-numberformat, currency.js, or dinero.js

Useful Number Methods

Rounding Done Right

const num = 42.6789;

Math.round(num);    // 43 (rounds to nearest)
Math.floor(num);    // 42 (always down)
Math.ceil(num);     // 43 (always up)
Math.trunc(num);    // 42 (removes decimal)

num.toFixed(2);     // "42.68" (returns STRING, not number!)
num.toPrecision(4); // "42.68" (significant digits)

// ⚠️ toFixed returns a string! Don't do math with it:
parseFloat(num.toFixed(2)) + 1; // 43.68 ✓
num.toFixed(2) + 1;            // "42.681" ✗ (string concat!)

Clamping Values

// Keep number between min and max
function clamp(value, min, max) {
  return Math.min(Math.max(value, min), max);
}

clamp(-5, 0, 100);   // 0
clamp(50, 0, 100);   // 50
clamp(150, 0, 100);  // 100

// Or with Math.clamp (newer browsers/Node)
Math.clamp(-5, 0, 100); // 0

Random Numbers

// Basic random
Math.random();                    // 0.123... (0 ≤ x < 1)

// Random integer between min and max (inclusive)
function randomInt(min, max) {
  min = Math.ceil(min);
  max = Math.floor(max);
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

randomInt(1, 10);   // 1-10 inclusive
randomInt(0, 1);    // 0 or 1 (coin flip)

// Random element from array
const items = ['rock', 'paper', 'scissors'];
items[Math.floor(Math.random() * items.length)];

// Shuffle array (Fisher-Yates)
function shuffle(arr) {
  const result = [...arr];
  for (let i = result.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [result[i], result[j]] = [result[j], result[i]];
  }
  return result;
}

shuffle([1, 2, 3, 4, 5]); // [3, 1, 5, 2, 4] (random order)

// Random hex color
'#' + Math.floor(Math.random()*16777215).toString(16).padStart(6, '0');
// "#a3f2c1"

// Random ID generator
Math.random().toString(36).substring(2, 10);
// "x7k2m9np"

Number Formatting

// Add commas to large numbers
function formatNumber(num) {
  return num.toLocaleString('en-US');
}

formatNumber(1000000);       // "1,000,000"
formatNumber(1234567.89);    // "1,234,567.89"
formatNumber(0.9876);        // "0.988" (auto rounds)

// Currency formatting
function formatCurrency(amount, currency = 'USD') {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency,
  }).format(amount);
}

formatCurrency(1234.56);        // "$1,234.56"
formatCurrency(1234.56, 'EUR');  // "€1,234.56"
formatCurrency(1234.56, 'JPY');  // "¥1,235" (no decimals for JPY)

// Percentage
function formatPercent(num, decimals = 1) {
  return new Intl.NumberFormat('en-US', {
    style: 'percent',
    minimumFractionDigits: decimals,
    maximumFractionDigits: decimals,
  }).format(num);
}

formatPercent(0.867);   // "86.7%"
formatPercent(0.05);     // "5.0%"

// Compact notation (1.2K, 3.4M)
function formatCompact(num) {
  return new Intl.NumberFormat('en-US', {
    notation: 'compact',
    compactDisplay: 'short',
  }).format(num);
}

formatCompact(1500);     // "1.5K"
formatCompact(2500000);  // "2.5M"
formatCompact(999500);   // "1M" (not 999K)

// Bytes to human readable
function formatBytes(bytes, decimals = 2) {
  if (bytes === 0) return '0 Bytes';
  const k = 1024;
  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(decimals)) + ' ' + sizes[i];
}

formatBytes(1024);           // "1 KB"
formatBytes(1048576);         // "1 MB"
formatBytes(1073741824);      // "1 GB"
formatBytes(15360000);       // "14.65 MB"

Parsing Numbers Safely

// ❌ Dangerous
parseInt('123abc');    // 123 (silently ignores non-numbers!)
parseInt('');          // NaN
parseInt(null);        // NaN
parseInt(true);        // NaN
parseInt('0x10');      // 16 (hex! might not be what you want)
parseFloat('  42.5 ');   // 42.5 (trims whitespace)

// ✅ Safe parsing
function safeParseInt(val, fallback = 0) {
  const parsed = parseInt(val, 10);
  return isNaN(parsed) ? fallback : parsed;
}

function safeParseFloat(val, fallback = 0) {
  const parsed = parseFloat(val);
  return isNaN(parsed) ? fallback : parsed;
}

safeParseInt('123abc', 0);  // 123 (still accepts this)
safeParseInt('abc', 0);      // 0 ← fallback
safeParseInt('', -1);        // -1 ← fallback

// ✅ Even safer: validate first
function isNumeric(str) {
  if (typeof str === 'number') return !isNaN(str);
  if (typeof str !== 'string') return false;
  return !isNaN(str) && !isNaN(parseFloat(str)) && isFinite(str);
}

isNumeric('42');       // true
isNumeric('42px');      // false
isNumeric('');          // false
isNumeric(null);        // false
isNumeric(Infinity);    // false

Math Tricks That Save Time

// Min/Max without Math.min/max (for small arrays)
const min = [3, 1, 4, 1, 5].sort((a,b)=>a-b)[0]; // 1
const max = [...[3, 1, 4, 1, 5]].sort((a,b)=>b-a)[0]; // 5

// But Math is faster for large arrays:
Math.min(...[3, 1, 4, 1, 5]); // 1
Math.max(...[3, 1, 4, 1, 5]); // 5

// ⚠️ Math.max/min spread can overflow the stack for huge arrays (>~65K elements)

// Power of 2 check
function isPowerOf2(n) {
  return n > 0 && (n & (n - 1)) === 0;
}
isPowerOf2(8);    // true
isPowerOf2(7);    // false
isPowerOf2(1024); // true

// Between two numbers
function between(n, min, max) {
  return n >= min && n <= max;
}
// Or clamp it: Math.min(max, Math.max(min, n))

// Distance between two numbers
function distance(a, b) {
  return Math.abs(a - b);
}

// Linear interpolation (lerp)
function lerp(start, end, t) {
  return start + (end - start) * t;
}
lerp(0, 100, 0.5); // 50
lerp(0, 100, 0.25); // 25

// Map value from one range to another
function mapRange(value, inMin, inMax, outMin, outMax) {
  return outMin + ((outMax - outMin) * (value - inMin)) / (inMax - inMin);
}
mapRange(5, 0, 10, 0, 100); // 50
mapRange(7, 0, 10, 0, 1);   // 0.7

// Average
function average(...nums) {
  return nums.reduce((a, b) => a + b, 0) / nums.length;
}
average(1, 2, 3, 4, 5); // 3

// Median
function median(nums) {
  const sorted = [...nums].sort((a, b) => a - b);
  const mid = Math.floor(sorted.length / 2);
  return sorted.length % 2 !== 0
    ? sorted[mid]
    : (sorted[mid - 1] + sorted[mid]) / 2;
}
median([1, 2, 3, 4, 5]); // 3
median([1, 2, 3, 4]);    // 2.5

// Sum
function sum(nums) {
  return nums.reduce((a, b) => a + b, 0);
}
sum([1, 2, 3, 4, 5]); // 15

// Percent change
function percentChange(oldVal, newVal) {
  if (oldVal === 0) return newVal > 0 ? Infinity : 0;
  return ((newVal - oldVal) / Math.abs(oldVal)) * 100;
}
percentChange(100, 150);   // 50 (% increase)
percentChange(100, 50);    // -50 (% decrease)
percentChange(0, 50);      // Infinity (from zero)

Weird JavaScript Number Facts

// These are all TRUE in JavaScript:

typeof NaN === 'number'              // NaN IS a number type!
NaN === NaN                        // false (NaN is never equal to itself)
Number.isNaN(NaN)                   // true (correct way to check)

Infinity === 1/0                     // true
-Infinity === -1/0                  // true
1 / 0 === Infinity                 // true
0 / 0 === NaN                      // true

Number.MAX_VALUE + 1 === Number.MAX_VALUE  // true (overflow stays at MAX)
Number.MIN_VALUE > 0                       // true (smallest positive fraction)
Number.MAX_SAFE_INTEGER === 9007199254740991  // 2^53 - 1
Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2  // true (precision lost!)

Number.isInteger(42)    // true
Number.isInteger(42.0)  // true
Number.isSafeInteger(Number.MAX_SAFE_INTEGER + 1)  // false

// ParseInt quirks:
parseInt(1e21);        // 1 (too big for int)
parseInt('1e21');      // 1 (same)
parseInt('0x10');      // 16 (hex detected)
parseInt('010');       // 10 (old behavior was octal, now decimal)
parseInt('');           // NaN
parseInt(null);         // NaN
parseInt([]);           // 0 (!!! coerces to "")
parseInt([5]);         // 5 (!!! coerces to "5")

// Bitwise operators truncate to 32-bit integers:
| 0;                    // 0 (fast floor for positive numbers)
~~1.9;                 // 1 (double tilde = fast Math.floor for positives)
1.9 | 0;               // 1

Quick Reference Card

Task	Code
Round to 2 decimals	`+(n.toFixed(2))` or `Math.round(n*100)/100`
Integer from float	`Math.trunc(n)` or `n \
Clamp	{% raw %}`Math.min(max, Math.max(min, n))`
Random int 1-10	`Math.floor(Math.random() * 10) + 1`
Is integer?	`Number.isInteger(n)`
Is safe int?	`Number.isSafeInteger(n)`
Is NaN?	`Number.isNaN(n)` (NOT global isNaN!)
Format as $	`n.toLocaleString('en-US',{style:'currency'})`
Parse safely	`parseInt(str, 10)` always specify radix!
Sum array	`arr.reduce((a,b)=>a+b, 0)`
Unique random IDs	`Math.random().toString(36).slice(2)`

What's your favorite number trick?

Follow @armorbreak for more practical JS guides.

Node.js Streams: The Practical Guide (2026)

Alex Chen — Wed, 20 May 2026 00:35:14 +0000

Node.js Streams: The Practical Guide (2026)

Streams are one of Node.js's most powerful features. Here's how to actually use them.

Why Streams Matter

Without streams:
  read entire file into memory → process → write entire result
  Memory usage: 100MB for a 100MB file
  Problem: What if the file is 10GB?

With streams:
  read chunk by chunk → process each chunk → write chunk by chunk
  Memory usage: ~64KB regardless of file size
  Result: Process files larger than RAM

The 4 Stream Types

Type	Used For	Example
Readable	Reading data	`fs.createReadStream()`, HTTP requests
Writable	Writing data	`fs.createWriteStream()`, HTTP responses
Duplex	Both reading & writing	TCP sockets, WebSocket
Transform	Modify data between read/write	`zlib`, CSV parsing

Basic Example: File Copy

const fs = require('fs');

// ❌ BAD — Loads everything into memory
const data = fs.readFileSync('large-file.txt');
fs.writeFileSync('copy.txt', data);

// ✅ GOOD — Streams in chunks (64KB memory)
const readStream = fs.createReadStream('large-file.txt');
const writeStream = fs.createWriteStream('copy.txt');

readStream.pipe(writeStream);

// That's it. One line.

pipe() — The Magic Method

readableStream.pipe(writableStream);

What it does:

Listens for data events from readable
Writes each chunk to writable
Handles backpressure (slows down if writable can't keep up)
Closes writable when readable ends

// Chaining pipes (Unix philosophy in JavaScript)
fs.createReadStream('input.txt')
  .pipe(zlib.createGzip())           // Compress
  .pipe(crypto.createCipheriv(...))  // Encrypt
  .pipe(fs.createWriteStream('output.gz.enc'));  // Write

// Data flows left → right through each transform

Real-World Use Cases

1. Processing Large Files (CSV Example)

const fs = require('fs');
const { pipeline } = require('stream/promises'); // Node 18+
const { Transform } = require('stream');

// A transform that processes CSV rows
class CSVParse extends Transform {
  constructor(options) {
    super({ ...options, objectMode: true });
    this.buffer = '';
    this.header = null;
  }

  _transform(chunk, encoding, callback) {
    this.buffer += chunk.toString();
    const lines = this.buffer.split('\n');

    // Keep last incomplete line in buffer
    this.buffer = lines.pop();

    for (const line of lines) {
      if (!line.trim()) continue;

      if (!this.header) {
        this.header = line.split(',');
        continue;
      }

      const values = line.split(',');
      const row = {};
      this.header.forEach((h, i) => row[h] = values[i]);
      this.push(row); // Output object mode
    }

    callback();
  }
}

async function processLargeCSV(inputPath) {
  const results = [];

  await pipeline(
    fs.createReadStream(inputPath),
    new CSVParse(),
    new Transform({
      objectMode: true,
      transform(row, _enc, callback) {
        // Process each row independently
        if (Number(row.price) > 1000) {
          results.push(row);
        }
        callback();
      }
    })
  );

  console.log(`Found ${results.length} expensive items`);
  return results;
}

2. HTTP Request Streaming

const https = require('https');
const fs = require('fs');

// Download large file with progress
function download(url, destPath) {
  return new Promise((resolve, reject) => {
    const file = fs.createWriteStream(destPath);
    let downloadedBytes = 0;

    https.get(url, (response) => {
      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
        // Handle redirect
        download(response.headers.location, destPath).then(resolve).catch(reject);
        return;
      }

      if (response.statusCode !== 200) {
        reject(new Error(`Status: ${response.statusCode}`));
        return;
      }

      const totalSize = parseInt(response.headers['content-length'], 10);

      response.on('data', (chunk) => {
        downloadedBytes += chunk.length;

        if (totalSize) {
          const percent = ((downloadedBytes / totalSize) * 100).toFixed(1);
          process.stdout.write(`\rDownloaded: ${percent}% (${downloadedBytes}/${totalSize})`);
        }
      });

      response.pipe(file);

      file.on('finish', () => {
        file.close();
        console.log('\nDownload complete!');
        resolve();
      });
    }).on('error', reject);
  });
}

await download('https://example.com/large-file.zip', './file.zip');

3. API Response Streaming

const express = require('express');
const app = express();

// Stream JSON array as NDJSON (one object per line)
app.get('/api/users-stream', (_req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');

  // Simulate streaming from database
  const users = [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' },
    // ... thousands more
  ];

  // Write header
  res.write('[\n');

  users.forEach((user, index) => {
    const isLast = index === users.length - 1;
    const json = JSON.stringify(user) + (isLast ? '\n]' : ',\n');
    res.write(json);
  });

  res.end();
});

// Client can parse incrementally:
// Each line arrives as soon as it's written
// No need to wait for full response

4. Log Aggregation (Multiple Sources → One File)

const fs = require('fs');
const net = require('net');

// Server that accepts log lines from multiple sources
const server = net.createServer((socket) => {
  socket
    .pipe(splitStream())         // Split by newline
    .pipe(timestampTransform())   // Add timestamp
    .pipe(formatTransform())       // Format nicely
    .pipe(fs.createWriteStream('all-logs.log', { flags: 'a' })); // Append
});

server.listen(4000, () => console.log('Log aggregator on :4000'));

Error Handling in Streams

const fs = require('fs');

const readStream = fs.createReadStream('input.txt');
const writeStream = fs.createWriteStream('output.txt');

// ❌ Errors are silent by default!
readStream.pipe(writeStream);

// ✅ Handle errors properly
readStream
  .on('error', (err) => {
    console.error('Read error:', err.message);
    writeStream.destroy(); // Don't leave writer hanging
  })
  .pipe(writeStream)
  .on('error', (err) => {
    console.error('Write error:', err.message);
  })
  .on('finish', () => {
    console.log('Done!');
  });

// Or use pipeline (Node 18+):
const { pipeline } = require('stream/promises');

try {
  await pipeline(
    fs.createReadStream('input.txt'),
    myTransform,
    fs.createWriteStream('output.txt')
  );
  console.log('Pipeline completed successfully');
} catch (err) {
  console.error('Pipeline failed:', err.message);
}

Backpressure Explained

// Backpressure = when writable is slower than readable
// Good news: pipe() handles this automatically!

// Manual backpressure:
function manualBackpressure(readable, writable) {
  readable.on('data', (chunk) => {
    const canWrite = writable.write(chunk);

    if (!canWrite) {
      // Pause readable until writable drains
      readable.pause();
      writable.once('drain', () => {
        readable.resume();
      });
    }
  });
}

// But seriously, just use .pipe() or pipeline()

Creating Your Own Transform

const { Transform } = require('stream');

// Uppercase transform
class UpperCase extends Transform {
  _transform(chunk, encoding, callback) {
    this.push(chunk.toString().toUpperCase());
    callback();
  }
}

// JSON parser (handles multi-chunk objects)
class JSONParser extends Transform {
  constructor(options) {
    super({ ...options, objectMode: true });
    this.buffer = '';
  }

  _transform(chunk, encoding, callback) {
    this.buffer += chunk.toString();

    try {
      // Try to parse complete objects from buffer
      while (this.buffer.length > 0) {
        const obj = JSON.parse(this.buffer);
        this.push(obj);
        this.buffer = ''; // Consumed successfully
      }
    } catch (e) {
      // Incomplete JSON, wait for more data
    }

    callback();
  }
}

// Usage
fs.createReadStream('data.jsonl')  // One JSON object per line
  .pipe(new JSONParser())
  .on('data', (obj) => {
    console.log('Parsed:', obj);
  });

Stream vs Buffer: When to Use Which

Use BUFFER when:
→ Small data (< 10MB)
→ Need random access
→ Data must be fully loaded before processing
→ Example: Config files, API responses under 1MB

Use STREAM when:
→ Large or unknown size data
→ Processing can start before all data arrives
→ Memory efficiency matters
→ Example: File processing, API proxies, log aggregation, real-time data

Quick Reference

// Create streams
fs.createReadStream(path, { highWaterMark: 64 * 1024 })  // Chunk size
fs.createWriteStream(path, { flags: 'a' })            // Append mode
new stream.PassThrough()                               // Identity transform
new stream.Readable({ read(_size) { this.push(data); } })  // Custom readable
new stream.Writable({ write(chunk, _enc, cb) { cb(); } })  // Custom writable

// Events
stream.on('data', (chunk) => {})     // New chunk available
stream.on('end', () => {})            // No more data
stream.on('error', (err) => {})       // Something went wrong
stream.on('finish', () => {})         // Write complete
stream.on('close', () => {})          // Stream destroyed
stream.on('drain', () => {})          // Safe to write again (backpressure)

// Methods
stream.pause()                       // Pause reading
stream.resume()                      // Resume reading
stream.destroy()                     // Close and cleanup
stream.pipe(destination)             // Connect streams
stream.unpipe(destination)           // Disconnect

// Async iteration (Node 18+) — cleanest API!
for await (const chunk of readableStream) {
  processChunk(chunk);
}

Are you using streams enough? Or still loading everything into memory?

Follow @armorbreak for more practical Node.js guides.

The JavaScript Event Loop Explained Simply (2026)

Alex Chen — Tue, 19 May 2026 20:35:05 +0000

The JavaScript Event Loop Explained Simply (2026)

Understanding the event loop is the difference between "Node.js works" and "I know why Node.js works."

The Big Picture

JavaScript is single-threaded.
But it handles thousands of concurrent connections.

How? The Event Loop.

Think of it like a restaurant with one chef:
→ One order at a time (single thread)
→ But while food cooks, take the next order (non-blocking I/O)
→ Never idle — always something to do

The Call Stack

function multiply(a, b) {
  return a * b;
}

function square(n) {
  return multiply(n, n);
}

function printSquare(x) {
  const result = square(x);
  console.log(result);
}

printSquare(4); // What happens?

Step-by-step execution:

┌─────────────┐
│ printSquare │  ← push
│   square    │  ← push (calls square)
│   multiply  │  ← push (calls multiply)
│   return 16 │  ← pop (multiply returns)
│   return 16 │  ← pop (square returns)
│    log: 16  │  ← pop (console.log executes)
└─────────────┘

Stack empties out → program ends

This is synchronous. Simple. Boring. Let's make it interesting:

Callbacks Enter The Chat

console.log('1');

setTimeout(() => {
  console.log('2');
}, 1000);

console.log('3');

// Output: 1 → 3 → 2 (NOT 1 → 2 → 3!)

Why? Because setTimeout is asynchronous — it doesn't block the call stack.

The Full Event Loop Model

┌───────────────────────────┐
│                           │
│   ┌───────────────────┐  │
│   │   Call Stack       │  │  ← Your code runs here (LIFO)
│   │  - printSquare()   │  │
│   │  - square()        │  │
│   │  - multiply()      │  │
│   └─────────┬─────────┘  │
│             │             │
│             ▼             │
│   ┌───────────────────┐  │
│   │ Web APIs          │  │  ← Browser/Node runtime handles these:
│   │ - setTimeout      │  │     (DOM events, fetch, timers, etc.)
│   │ - fetch           │  │
│   │ - DOM events      │  │
│   └─────────┬─────────┘  │
│             │             │
│             ▼ (callback ready)
│   ┌───────────────────┐  │
│   │ Callback Queue    │  │  ← Waiting their turn
│   │ (Task Queue)      │  │
│   └─────────┬─────────┘  │
│             │             │
│             ▼             │
│   ┌───────────────────┐  │
│   │   EVENT LOOP      │  │  ← The conductor!
│   │ "Is stack empty?"  │  │  If yes → dequeue callback → push to stack
│   └───────────────────┘  │
│                           │
└───────────────────────────┘

Visual Walkthrough

console.log('Start');

setTimeout(() => {
  console.log('Timeout 1 (0ms)');
}, 0);

setTimeout(() => {
  console.log('Timeout 2 (100ms)');
}, 100);

Promise.resolve().then(() => {
  console.log('Microtask');
});

console.log('End');

Output: Start → End → Microtask → Timeout 1 (0ms) → Timeout 2 (100ms)

Why does Microtask run before Timeout?

There are actually two queues:

Microtask Queue (higher priority):
  - Promise.then/catch/finally
  - queueMicrotask()
  - MutationObserver

Macrotask Queue (lower priority):
  - setTimeout / setInterval
  - I/O callbacks
  - UI rendering (browser)

Event Loop Priority:

1. Run everything in call stack until empty
2. Run ALL microtasks (drain entire microtask queue)
3. Run ONE macrotask
4. Go back to step 2 (check for new microtasks)

This means: Microtasks can starve macrotasks!

Practical Example: Why This Matters

Example 1: Non-Blocking I/O

const fs = require('fs');

console.log('Reading file...');

fs.readFile('/etc/hostname', 'utf8', (err, data) => {
  // This callback goes to the queue
  // Event loop picks it up when I/O completes
  console.log('File contents:', data);
});

console.log('This logs BEFORE file read!');

// Output:
// Reading file...
// This logs BEFORE file read!
// File contents: <hostname>

The readFile offloads work to the OS (thread pool). Your JS keeps running. When data arrives, callback enters the queue.

Example 2: The Starvation Problem

let counter = 0;

// This creates an infinite loop of microtasks
function scheduleMicrotask() {
  Promise.resolve().then(() => {
    counter++;
    if (counter < 10_000) {
      scheduleMicrotask();
    }
  });
}

scheduleMicrotask();

setTimeout(() => {
  console.log('Timer fired! Counter:', counter);
}, 0);

// When does "Timer fired!" log?
// Answer: NEVER (or after all 10,000 microtasks complete)
// The timer callback waits in the macrotask queue forever

Example 3: setImmediate vs setTimeout(fn, 0)

// Node.js specific
setTimeout(() => console.log('setTimeout'), 0);
setImmediate(() => console.log('setImmediate'));

// In Node.js: setImmediate fires FIRST (usually)
// Why? setImmediate checks the check queue (poll phase)
// setTimeout(0) uses the timer queue (timer phase)
// Timer phase comes before poll phase... but 0ms might round up

async/await Is Just Syntactic Sugar

// These are IDENTICAL from event loop perspective:

async function getData() {
  const res = await fetch(url);  // await = yield + resume
  return res.json();
}

// Compiles to roughly:
function getData() {
  return fetch(url)
    .then(res => res.json());
}

// Each await pauses function execution
// Puts the rest into a microtask (.then callback)
// Continues when promise resolves

Common Misconceptions

❌ "setTimeout(fn, 0) runs immediately"

No. It runs as soon as the call stack is empty AND the current turn of the event loop finishes. Minimum delay is typically ~1ms (or more under load).

❌ "setTimeout guarantees timing"

No. It guarantees MINIMUM delay. If the stack is busy with heavy computation, your callback waits.

const start = Date.now();

setTimeout(() => {
  console.log(`Actual delay: ${Date.now() - start}ms`);
}, 100);

// Block for 200ms
const end = Date.now() + 200;
while (Date.now() < end) {}

// Output: Actual delay: ~201ms (not 100!)

❌ "Web Workers add threads to JavaScript"

Workers have their OWN event loop, own stack, own memory. They don't share memory with main thread. Communication via message passing. True parallelism, but no shared state.

Performance Implications

// ❌ Blocking the event loop
app.get('/heavy', (req, res) => {
  const result = crypto.pbkdf2Sync(password, salt, 100000, 512, 'sha256'); // Takes 500ms
  res.json({ result });
});
// During this 500ms, NO other request can be processed!

// ✅ Offload or break up
app.get('/heavy', async (req, res) => {
  const result = await new Promise((resolve) => {
    // Use worker_threads or break into chunks
    pbkdf2(password, salt, 100000, 512, 'sha256', (err, key) => {
      resolve(key.toString('hex'));
    });
  });
  res.json({ result });
});

// Or even simpler — use built-in async version if available
import { pbkdf2 } from 'node:crypto';
const result = await pbkdf2(password, salt, 100000, 512, 'sha256');
// Doesn't block because it uses thread pool internally

Debugging Event Loop Issues

// Latency measurement
function measureLatency(label) {
  const start = process.hrtime.bigint();

  return {
    done: () => {
      const ns = Number(process.hrtime.bigint() - start);
      const ms = ns / 1_000_000;
      console.log(`${label}: ${ms.toFixed(2)}ms`);
      return ms;
    }
  }

// Usage
const m = measureLatency('API Call');
await fetchData();
m.done(); // API Call: 45.23ms

// Detect event loop blocking
let lastTime = Date.now();

setInterval(() => {
  const now = Date.now();
  const delta = now - lastTime;
  lastTime = now;

  if (delta > 50) { // More than 50ms between ticks = blocked
    console.warn(`⚠️ Event loop blocked for ${delta}ms!`);
  }
}, 10); // Check every 10ms

Quick Reference

Mechanism	Queue Type	Typical Use
`Promise.then`	Microtask	Async flow control
`queueMicrotask()`	Microtask	Explicit microtask scheduling
`process.nextTick()`	Microtask (Node)	After current operation
`setTimeout(fn, 0)`	Macrotask	"After current code"
`setImmediate()`	Macrotask (Node)	"After I/O phase"
`setInterval()`	Macrotask	Repeating tasks
`requestAnimationFrame()`	Macrotask (Browser)	Before next paint

Does the event loop finally click for you?

Follow @armorbreak for more deep-dive JS guides.

Debugging Node.js Like a Pro: My Debugging Workflow (2026)

Alex Chen — Tue, 19 May 2026 18:35:02 +0000

Debugging Node.js Like a Pro: My Debugging Workflow (2026)

Stop using console.log everywhere. Here's my systematic approach to finding bugs fast.

The Debugging Mindset

Before touching code:
1. What exactly is the symptom? (Not your guess — the actual behavior)
2. When does it happen? (Every time? Intermittent? Under load?)
3. What changed recently? (Code, deps, environment, data)

The bug is never where you think it is.
The log message that will reveal it is never the one you want to write.

Level 1: Console (But Smarter)

// ❌ SCATTERSHOT debugging
console.log('here');
console.log('data:', data);
console.log('after function');

// ✅ STRUCTURED logging
const debug = require('debug')('myapp:user');
debug('Creating user with email=%s', email);
// Set DEBUG=myapp:* to see these, empty string to hide

// ✅ NAMED console groups
console.group('🔍 Auth Flow');
  console.log('Token received:', token.substring(0, 10) + '...');
  console.log('Expires at:', new Date(expires * 1000));
  console.groupDecoded('Payload');
    console.log(decoded);
  console.groupEnd();
console.groupEnd();

// ✅ TABLE for objects/arrays
console.table(users.map(u => ({ id: u.id, email: u.email, role: u.role })));

// ✅ COUNTER for loops
let i = 0;
items.forEach(item => {
  console.count('processed'); // auto-increments each call
  process(item);
});
console.countReset('processed'); // reset when done

// ✅ TIME for performance
console.time('db-query');
const users = await db.query('SELECT * FROM users');
console.timeEnd('db-query'); // → db-query: 142ms

// ✅ TRACE for call stack
function deepFunction() {
  console.trace('How did I get here?'); // Shows full stack trace
}

// ✅ ASSERT for invariants
const assert = require('node:assert/strict');
assert(user.email.includes('@'), 'Email should contain @', { email: user.email });
assert(response.status < 400, `Unexpected status: ${response.status}`);

Level 2: Node.js Built-in Debugger

# Start debugger (breaks on first line)
node inspect server.js

# Or break on first statement of a script
node --inspect-brk script.js

# Attach to running process
node --inspect=9229 server.js
# Then connect from Chrome: chrome://inspect

Debugger Commands

c(ontinue)        # Resume execution
n(ext)            # Step over (don't enter functions)
s(tep)           # Step into (enter functions)
o(ut)            # Step out of current function
pa(use)          # Pause code execution
re(sum)          # Resume execution

Programmatic Breakpoints

// Conditional breakpoint — only stops when condition is true
debugger; // Always stops

if (userId === 'problematic-user-123') {
  debugger; // Only stops for this user
}

if (data.length > 10000) {
  debugger; // Stops when data looks suspicious
}

Level 3: VS Code Debugger (Game Changer)

launch.json Configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Server",
      "program": "${workspaceFolder}/server.js",
      "cwd": "${workspaceFolder}",
      "env": { "NODE_ENV": "development" },
      "runtimeArgs": ["--inspect"],
      "console": "integratedTerminal",
      "restart": true,
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Running",
      "port": 9229,
      "restart": true,
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Run Tests",
      "program": "${workspaceFolder}/node_modules/.bin/node",
      "args": ["--test", "--test-reporter", "spec", "${workspaceFolder}/tests"],
      "console": "integratedTerminal"
    }
  ]
}

Must-Know Features

Watch Expressions: Monitor variables that update in real-time as you step.

Call Stack Panel: See exactly how you got here. Click any frame to see local variables at that point.

Breakpoint Conditions: Right-click breakpoint → "Edit Breakpoint" → Add condition:

users.length > 50  // Only breaks when array has > 50 items
email.includes('test')  // Only breaks for test emails
i === 42  // Only breaks on specific iteration

Logpoints: Non-breaking breakpoints that log messages:

Right-click line number → "Add Logpoint"
Enter: "User ID: {userId}, Role: {role}"
→ Shows in debug console without pausing execution!

Inline Values: Enable in VS Code settings:

{
  "debug.inlineValues": "on"  // Shows variable values inline in editor
}

Level 4: Async Debugging

This is where most developers get stuck:

// ❌ Can't see inside this easily
async function processData() {
  const data = await fetch(url);     // What's in data?
  const parsed = await data.json();   // And here?
  const result = await transform(parsed); // ???
  return result;
}

// ✅ Break INSIDE async functions
async function processData() {
  const data = await fetch(url);     
  debugger; // ← Inspect data here
  const parsed = await data.json();   
  debugger; // ← Inspect parsed here  
  const result = await transform(parsed); 
  return result;
}

// ✅ Or use .then() chain for stepping
fetch(url)
  .then(r => r.json())
  .then(data => { debugger; return data; }) // Breaks here
  .then(transform);

Promise rejection handling:

// Catch ALL unhandled rejections
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
  // Don't crash in dev, but log everything
  if (process.env.NODE_ENV === 'production') {
    process.exit(1);
  }
});

// In tests or critical paths:
await expectAsync(() => somePromise()).resolves.toBeDefined();

Level 5: Memory Leaks

// Detect growing memory
setInterval(() => {
  const mem = process.memoryUsage();
  console.log(`Heap: ${(mem.heapUsed / 1024 / 1024).toFixed(0)}MB | RSS: ${(mem.rss / 1024 / 1024).toFixed(0)}MB`);
}, 10_000);

// Take heap snapshots in Chrome DevTools
// Compare snapshot A vs B → see what grew

Common leak patterns:

// ❌ Global variable accumulation
global.cache = global.cache || [];
global.cache.push(heavyObject); // Never cleaned up!

// ❌ Event listener not removed
emitter.on('data', handler); // Never off()
// Fix: emitter.once() when possible, or track and remove

// ❌ Closure holding references
function createHandler() {
  const hugeData = new Array(1000000).fill('x');
  return () => { /* closure keeps hugeData alive */ };
}

// ✅ WeakMap for cache (GC-friendly)
const cache = new WeakMap();
cache.set(obj, heavyData); // Auto-cleaned when obj is GC'd

Production Debugging

// src/middleware/errorLogger.js
module.exports = (err, req, res, _next) => {
  const errorId = Date.now().toString(36) + Math.random().toString(36).slice(2);

  // Log structured error
  const errorLog = {
    id: errorId,
    timestamp: new Date().toISOString(),
    error: err.message,
    stack: err.stack,
    path: req.path,
    method: req.method,
    ip: req.ip,
    userId: req.user?.id,
    body: req.body,
    headers: {
      'user-agent': req.headers['user-agent'],
      'content-type': req.headers['content-type']
    }
  };

  console.error(JSON.stringify(errorLog)); // Structured JSON for log aggregation

  // In production: don't expose internals
  const statusCode = err.statusCode || 500;
  res.status(statusCode).json({
    error: {
      code: err.code || 'INTERNAL_ERROR',
      message: process.env.NODE_ENV === 'production' 
        ? `Internal error (ref: ${errorId})` 
        : err.message,
      ref: errorId
    }
  });
};

My Debugging Checklist

When a bug report comes in:

□ Reproduce locally (same inputs, same env)
□ Check recent changes (git log --since="1 week ago")
□ Read the ACTUAL error message (not what you think it says)
□ Check logs around the timestamp
□ Add ONE strategic debugger/console.log
□ Verify assumptions (is the var really what you think?)
□ Simplify (remove layers until it works, then add back)
□ Check edge cases (empty, null, huge, unicode, concurrent)
□ Ask: "What if the data is different than expected?"
□ After fix: Write a test that would have caught this

What's your go-to debugging trick? Console.log ninja or IDE power user?

Follow @armorbreak for more practical Node.js guides.

Environment Variables Done Right: The .env Guide Every Developer Needs (2026)

Alex Chen — Tue, 19 May 2026 00:35:15 +0000

Environment Variables Done Right: The .env Guide Every Developer Needs (2026)

Stop hardcoding secrets. Stop losing config between environments. Here's how to manage env vars like a pro.

Why Environment Variables Matter

// ❌ NEVER do this
const DB_PASSWORD = 'SuperSecret123!';
const API_KEY = 'sk-live-abc123456789';
const STRIPE_SECRET = 'sk_live_...';

// These end up in git, in logs, in your brain (worst of all)

// ✅ ALWAYS do this
const DB_PASSWORD = process.env.DB_PASSWORD;
const API_KEY = process.env.API_KEY;

The Basics

What Are Environment Variables?

Key-value pairs available to your process:

# Set in shell
export NODE_ENV=production
export PORT=3000

# Pass when running command
PORT=8080 node server.js

# From a file (.env)
DB_HOST=localhost DB_PORT=5432 node server.js

In Node.js

// All env vars live on process.env
console.log(process.env.HOME);        // /root
console.log(process.env.PATH);        // /usr/bin:...
console.log(process.env.NODE_ENV);    // undefined (unless set)
console.log(process.env.MY_VAR);      // whatever you set it to

The Standard: dotenv

npm install dotenv

// src/config/index.js — Load as early as possible
import dotenv from 'dotenv';
import { fileURLToPath } from 'url';
import path from 'path';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Load .env from project root (goes up from src/)
dotenv.config({ path: path.resolve(__dirname, '../../.env') });

// Now all vars are on process.env!
console.log(process.env.DATABASE_URL);

.env File Format

# .env — NEVER commit this file!

# Server
NODE_ENV=development
PORT=3000
HOST=0.0.0.0

# Database
DATABASE_URL=postgres://user:pass@localhost:5432/myapp
DATABASE_POOL_SIZE=10

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# JWT
JWT_SECRET=your-super-secret-key-at-least-32-chars
JWT_EXPIRES_IN=7d

# External APIs
OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_live_...

# Feature flags
ENABLE_CACHE=true
RATE_LIMIT=100

.env.example — For Your Team

# .env.example — COMMIT THIS FILE!

# Copy this to .env and fill in your values:
cp .env.example .env

# Server
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgres://user:pass@localhost:5432/myapp
DATABASE_POOL_SIZE=10

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# JWT — Generate with: openssl rand -base64 32
JWT_SECRET=change-me-in-production

# External APIs
OPENAI_API_KEY=
STRIPE_SECRET_KEY=

# Feature flags
ENABLE_CACHE=true
RATE_LIMIT=100

Validation (Don't Skip This!)

// src/config/index.js with validation
import dotenv from 'dotenv';
import path from 'path';

dotenv.config();

const requiredVars = [
  'NODE_ENV',
  'PORT',
  'DATABASE_URL',
  'JWT_SECRET',
];

const missingVars = requiredVars.filter(key => !process.env[key]);

if (missingVars.length > 0) {
  console.error('❌ Missing environment variables:');
  missingVars.forEach(v => console.error(`   - ${v}`));
  console.error('\nCopy .env.example to .env and fill in the values.');
  process.exit(1);
}

// Type-safe config with defaults
const config = {
  nodeEnv: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT) || 3000,

  database: {
    url: process.env.DATABASE_URL,
    poolSize: parseInt(process.env.DATABASE_POOL_SIZE) || 10,
  },

  jwt: {
    secret: process.env.JWT_SECRET,
    expiresIn: process.env.JWT_EXPIRES_IN || '7d',
  },

  isDev: () => (process.env.NODE_ENV || 'development') === 'development',
  isProd: () => process.env.NODE_ENV === 'production',
  isTest: () => process.env.NODE_ENV === 'test',
};

// Freeze in production to prevent accidental mutation
if (config.isProd()) {
  Object.freeze(config);
}

export default config;

Multi-Environment Setup

project/
├── .env                # Local dev (gitignored)
├── .env.development   # Dev overrides (optional)
├── .env.production     # Production template (committed)
├── .env.test           # Test values (committed)
├── .env.example        # Template for new devs (committed)
└── .gitignore          # Includes .env, .env.local

// Choose which .env file based on NODE_ENV
import dotenv from 'dotenv';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const envFile = `.env.${process.env.NODE_ENV || 'development'}`;

dotenv.config({ 
  path: path.resolve(__dirname, `../../${envFile}`),
  override: true 
});

// Fallback to default .env
dotenv.config({ path: path.resolve(__dirname, '../../.env') });

Docker + Environment Variables

# Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://app:secret@db:5432/appdb
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.production  # Load from file
    depends_on:
      - db
      - redis

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb

  redis:
    image: redis:7-alpine

Best practice: Use environment for shared/secrets and env_file for non-sensitive defaults.

Security Rules

1. Never Commit .env

# .gitignore (add these lines)
.env
.env.local
.env.*.local
*.env
!.env.example
!.env.production.template
!.env.test

2. Use Different Keys Per Environment

// Development can use weaker keys
// Production MUST use strong keys
if (config.isProd() && config.jwt.secret.length < 32) {
  throw new Error('JWT_SECRET must be at least 32 characters in production');
}

3. Rotate Secrets Regularly

# Generate new secrets
openssl rand -base64 32  # JWT secret
openssl rand -hex 32     # API key format

# Update .env and restart:
# 1. Change value in .env
# 2. Restart application
# 3. Update any external services that used old key

4. Don't Log Env Vars

// ❌ BAD
app.use((req, res, next) => {
  console.log('Config:', process.env); // Leaks ALL secrets!
  next();
});

// ✅ GOOD
app.use((req, res, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.path}`);
  next();
});

Debugging Common Issues

Problem	Cause	Fix
`undefined` when reading var	.env not loaded	Check dotenv.config() runs before imports
Var loads in dev but not prod	.env not deployed	Add to docker-compose or CI secrets
Special characters break	Quotes missing	Wrap values in quotes: `MSG="Hello World"`
Multiline value fails	No `\n` support	Use JSON or base64 for complex values
Test uses production values	Wrong .env file loaded	Explicitly set `NODE_ENV=test`

Advanced: Vault Integration (When You Scale)

For teams, use a secret manager instead of .env files:

// Using HashiCorp Vault (simplified)
async function loadFromVault() {
  if (process.env.VAULT_ADDR) {
    const response = await fetch(`${process.env.VAULT_ADDR}/v1/secret/data/app`);
    const { data } = await response.json();

    Object.entries(data.data).forEach(([key, val]) => {
      if (!process.env[key]) {
        process.env[key] = val;
      }
    });
  }
}

// Falls back to .env if no vault configured
await loadFromVault();
require('dotenv').config();

Quick Reference

# CLI operations
export MY_VAR="hello"              # Set for current session
unset MY_VAR                       # Remove
env                                 # Show all vars
printenv | grep NODE                 # Filter vars
source .env                         # Load into shell (not recommended)

# Node.js
process.env.MY_VAR                  # Read
process.env.MY_VAR = 'value'         # Write (affects current process only)
delete process.env.MY_VAR           # Remove

How do you manage environment variables? Still using .env everywhere or moved to something else?

Follow @armorbreak for more practical Node.js guides.