DEV Community: Stack Horizon

REST vs GraphQL in Practice

Stack Horizon — Tue, 25 Aug 2026 16:01:52 +0000

The Real Trade-offs

After building APIs with both REST and GraphQL, I've learned that the choice isn't about which is "better" but about what your consumers need. Here's a practical breakdown based on real projects.

REST: Predictable and Simple

REST is still my default for most public APIs. The model is straightforward: resources, HTTP methods, and status codes. Clients know exactly what to expect.

// REST: fetch a user and their posts separately
const user = await fetch('/users/1').then(r => r.json());
const posts = await fetch('/users/1/posts').then(r => r.json());

When REST shines:

Simple CRUD apps where resources map well to endpoints
Public APIs where you want predictable caching (GET requests are cacheable by default)
Teams familiar with HTTP semantics
When you don't need nested data often

The pain point: over-fetching and under-fetching. Your /users/1 endpoint returns everything, even if the client only needs a name. And if you need user + posts + comments, you're making multiple round trips.

GraphQL: Precise and Flexible

GraphQL lets clients ask for exactly what they need. One request, one response.

query {
  user(id: 1) {
    name
    posts {
      title
      comments { text }
    }
  }
}

When GraphQL shines:

Mobile apps with limited bandwidth (one request instead of many)
Complex, nested data relationships
Multiple client types (web, mobile, third-party) needing different data shapes
Rapid iteration where frontend needs change often

The pain point: complexity. You're now managing a schema, resolvers, and a query language. Caching is harder because GET-style caching doesn't work. And you can easily create performance problems with deeply nested queries.

Performance in Practice

I've seen teams assume GraphQL is always faster. It isn't. The classic N+1 problem is real.

// Bad: resolver that queries per post
const resolvers = {
  User: {
    posts: (user) => db.posts.find({ userId: user.id })
  }
}

If a client queries 10 users, that's 10 queries just for posts. You need DataLoader or similar batching:

const DataLoader = require('dataloader');
const postLoader = new DataLoader(ids => db.posts.find({ userId: { $in: ids } }));

const resolvers = {
  User: {
    posts: (user) => postLoader.load(user.id)
  }
}

That's extra code and thinking. REST doesn't have this problem because endpoints are fixed.

Tooling and Ecosystem

REST has mature tooling: OpenAPI specs, Postman collections, and every HTTP client works out of the box. GraphQL has GraphiQL and code generation, but you'll often need to build your own client logic.

For error handling, REST uses status codes (404, 500). GraphQL always returns 200 and puts errors in the response body, which can surprise developers expecting HTTP semantics.

My Rule of Thumb

Start with REST unless you have a clear need for GraphQL's flexibility.
Choose GraphQL if you have multiple clients with different data needs, or a complex domain with deep relationships.
Consider a hybrid: use REST for simple resources and add a GraphQL layer only where it adds value.

Practical Example: Both in One App

I worked on an app where we exposed REST for user management (simple CRUD) and GraphQL for the dashboard (which needed aggregated data from several services). It worked well because each tool did what it's best at.

// REST endpoint for simple actions
app.post('/api/users', createUser);

// GraphQL for complex queries
const server = new ApolloServer({ typeDefs, resolvers });

Final Thoughts

Don't let hype drive your decision. Evaluate your actual use cases. If your API is mostly CRUD and you control the clients, REST keeps things simple. If you have a data-heavy frontend with many views, GraphQL can save you time and bandwidth. Both are valid, and you can use them together.

Remember: the best API is one your team can maintain and your consumers can use without frustration.

TypeScript Features Worth Adopting First

Stack Horizon — Sat, 22 Aug 2026 00:00:33 +0000

Start with the essentials, not the entire type system

When you first adopt TypeScript, the sheer number of features can be overwhelming. You don't need to master every advanced type trick on day one. In my experience, a handful of features deliver 80% of the value and make your code safer and more readable immediately. Here are the ones I'd adopt first.

1. Explicit function return types

TypeScript can infer return types, but being explicit about them acts as documentation and catches mistakes early. If a function's logic changes and the return type shifts, the compiler will tell you instead of silently breaking callers.

function getUser(id: string): User {
  // ...
}

This is especially useful for complex functions or those used across a codebase. It also makes code review faster because the intent is clear.

2. `unknown` over `any`

any is the escape hatch that disables type checking. unknown is the safe counterpart: you can't use it without narrowing first. When dealing with data from APIs or user input, use unknown and then narrow with type guards.

function parseJson(raw: string): unknown {
  return JSON.parse(raw);
}

const data = parseJson('{"name":"Ada"}');
if (typeof data === 'object' && data !== null && 'name' in data) {
  console.log(data.name); // safe
}

This forces you to handle the unknown shape, preventing runtime errors.

3. Discriminated unions

When a value can be one of several shapes, a discriminated union uses a common property (the discriminant) to narrow the type. This is a clean replacement for error-prone if chains and makes exhaustive checks possible.

type Result =
  | { status: 'success'; data: string }
  | { status: 'error'; error: Error };

function handle(result: Result) {
  switch (result.status) {
    case 'success':
      console.log(result.data);
      break;
    case 'error':
      console.error(result.error.message);
      break;
  }
}

The compiler ensures you handle every case, and you get autocompletion for the specific properties.

4. `satisfies` operator (TypeScript 4.9+)

satisfies lets you check that a value matches a type without changing its inferred type. This is perfect for objects that need to meet a certain shape while keeping literal types for autocompletion.

const config = {
  port: 3000,
  env: 'development',
} satisfies Record<string, string | number>;

config.port; // number, not string | number

Without satisfies, you'd lose the specific literal types or have to use as which can hide errors.

5. `Readonly` and `readonly` properties

Immutability prevents accidental mutation bugs. Use readonly on properties and Readonly<T> for whole objects. It's a compile-time guarantee that doesn't affect runtime performance.

interface Point {
  readonly x: number;
  readonly y: number;
}

const origin: Readonly<Point> = { x: 0, y: 0 };
// origin.x = 1; // Error: Cannot assign to 'x' because it is a read-only property.

This is especially valuable in shared code or when passing objects around.

6. Utility types: `Partial`, `Pick`, `Omit`

These save you from writing repetitive interfaces. Partial<T> makes all properties optional, Pick<T, K> selects a subset, and Omit<T, K> excludes some. They're perfect for update payloads or derived types.

interface User {
  id: number;
  name: string;
  email: string;
}

type UserUpdate = Partial<Omit<User, 'id'>>;
// { name?: string; email?: string }

They keep your types DRY and adapt when the base interface changes.

7. `const` assertions

as const makes a value deeply readonly and narrows literal types. It's great for configuration objects or constants that shouldn't change.

const COLORS = {
  primary: '#3498db',
  secondary: '#2ecc71',
} as const;

// COLORS.primary is '#3498db', not string

This prevents accidental reassignment and gives you literal types for pattern matching.

8. `noUncheckedIndexedAccess` (strictness)

Enable this compiler option. It forces you to handle the possibility that an array index or object property access might return undefined. This eliminates a whole class of runtime errors.

const arr = [1, 2, 3];
const first = arr[0]; // number | undefined with the flag on
if (first !== undefined) {
  console.log(first.toFixed());
}

It's a small change that surfaces real bugs during development.

Start small, then expand

These features are a solid foundation. Once you're comfortable, you can explore advanced topics like conditional types, mapped types, and template literal types. But you don't need them to benefit from TypeScript. Adopt these first, and you'll see immediate improvements in code clarity and safety without drowning in complexity.

For more details, the TypeScript Handbook is the canonical reference, and the release notes explain new features like satisfies. Happy typing!

Debugging Node.js Like a Pro

Stack Horizon — Thu, 20 Aug 2026 16:01:46 +0000

Start with the Right Mindset

Debugging is not about guessing. It's about gathering evidence and narrowing down the problem systematically. In Node.js, the tools are built-in and powerful, but most developers only use console.log. Let's change that.

Use the Built-in Debugger

Node has a built-in debugger that you can start with node inspect. It's a step-by-step command-line debugger. For example:

node inspect app.js

Then you can use commands like cont, next, step, and list. But honestly, the CLI is clunky. The better approach is to use the Chrome DevTools protocol.

Debug with Chrome DevTools

Start your app with --inspect and open chrome://inspect in Chrome. You get a full graphical debugger: breakpoints, watch expressions, call stack, and scope inspection.

node --inspect app.js

For a break at the first line, use --inspect-brk. This is perfect for debugging startup issues.

Use `debug` for Logging

Instead of sprinkling console.log, use the debug package. It gives namespaced logging that you can turn on/off via the DEBUG environment variable.

const debug = require('debug');
const log = debug('app:server');
const db = debug('app:db');

log('Server starting');
db('Connecting to DB');

Run with DEBUG=app:* node app.js to see all app logs, or DEBUG=app:db to see only DB logs. This keeps your console clean in production.

Handle Unhandled Rejections and Exceptions

Silent failures are the worst. Add global handlers early in your app to catch what you missed.

process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
  // Application specific logging, throwing an error, or other logic
});

process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', err);
  // Best practice: log and exit, because the app is in an unknown state
  process.exit(1);
});

Use `node --trace-warnings`

If you see warnings about memory or deprecations, run with --trace-warnings to get stack traces for them. This helps identify where the warning originates.

node --trace-warnings app.js

Inspect Memory Leaks

Use the --inspect flag with Chrome DevTools to take heap snapshots. But for quick checks, use process.memoryUsage().

console.log(process.memoryUsage());

For a more detailed look, use the v8 module:

const v8 = require('v8');
console.log(v8.getHeapStatistics());

Use `async_hooks` for Async Debugging

Async code is hard to trace. The async_hooks module lets you track the lifecycle of async resources. It's advanced but invaluable for finding leaks or lost context.

const async_hooks = require('async_hooks');

const hooks = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    console.log(`Init ${type} with id ${asyncId}`);
  },
  destroy(asyncId) {
    console.log(`Destroy ${asyncId}`);
  }
});
hooks.enable();

Use it sparingly because it adds overhead.

Use `--stack-trace-limit`

By default, Node limits stack traces. Increase the limit to see more frames when debugging deep recursion or complex call chains.

node --stack-trace-limit=100 app.js

Use `util.inspect` for Deep Objects

console.log truncates nested objects. Use util.inspect with full depth.

const util = require('util');
console.log(util.inspect(myObject, { showHidden: false, depth: null, colors: true }));

Debug with `ndb` (Optional)

ndb is an improved debugging experience for Node.js, built by the Chrome DevTools team. It provides a standalone UI with better navigation. Install it globally and run ndb app.js. It's a nice upgrade over raw Chrome DevTools.

Wrap Up

Stop guessing. Use the built-in tools: --inspect, the debug package, and proper error handlers. These techniques will save you hours and make you a more effective Node.js developer.

Remember: the goal is to understand the problem, not to patch it blindly. Use the tools to see what's happening, then fix the root cause.

REST vs GraphQL in Practice

Stack Horizon — Tue, 18 Aug 2026 08:00:28 +0000

The Real Trade-offs

After building APIs with both REST and GraphQL, I've learned that the choice isn't about which is "better" but which fits your specific constraints. Here's what matters in practice, not in theory.

REST: The Workhorse

REST is predictable. You have endpoints, you get resources. It's easy to cache, easy to debug, and every tooling ecosystem supports it out of the box.

When REST shines

Public APIs where you want clear versioning and stable contracts
Simple CRUD apps where resources map directly to database tables
Caching matters (CDN, HTTP caching)
Teams that value simplicity over flexibility

The pain points

Over-fetching and under-fetching are real. A mobile app might need user + posts + comments, and you either make three requests or build a custom endpoint that becomes a maintenance burden.

// REST: three round trips
const user = await fetch('/users/1');
const posts = await fetch('/users/1/posts');
const comments = await fetch('/posts/1/comments');

GraphQL: The Flexible Alternative

GraphQL gives clients exactly what they ask for. One request, nested data, no over-fetching. The schema is self-documenting, and tooling like GraphiQL makes exploration easy.

When GraphQL shines

Mobile apps with limited bandwidth and need for precise data
Aggregating multiple services into one API layer
Rapid iteration where frontend needs change often
Complex relationships between entities

query {
  user(id: 1) {
    name
    posts {
      title
      comments { text }
    }
  }
}

The hidden costs

GraphQL shifts complexity to the server. You need to handle N+1 queries, caching is harder, and the flexible queries can be abused by clients.

// N+1 problem: naive resolver
const resolvers = {
  User: {
    posts: (parent) => db.posts.findByUserId(parent.id) // fires per user
  }
}

// Solution: DataLoader batching
const postsLoader = new DataLoader(ids => batchFetchPosts(ids));

My Decision Framework

I ask these questions before choosing:

Who consumes the API? Internal apps with varying needs? GraphQL. Public, fixed consumers? REST.
How important is caching? If you need CDN-level caching, REST wins easily.
How complex is the data graph? Simple resources: REST. Deeply nested relationships: GraphQL.
Team experience? If the team knows REST well and doesn't want to learn new concepts, stick with it.

Hybrid Approach

You don't have to go all-in. I've seen successful systems that expose a REST API for simple CRUD and a GraphQL endpoint for complex queries. This gives you the best of both worlds but doubles maintenance.

Practical Tips

If you choose GraphQL:

Use DataLoader to avoid N+1 queries
Implement query complexity limits to prevent expensive queries
Consider persisted queries for production performance

If you choose REST:

Design endpoints around resources, not actions
Use HTTP status codes properly
Version your API from day one

The Verdict

There's no universal winner. I've built production systems with both. REST is boring, reliable, and works. GraphQL is powerful, flexible, and demands more discipline. Choose based on your actual constraints, not hype.

For most small to medium projects, REST is perfectly fine. For complex, data-heavy applications with multiple clients, GraphQL can save you time in the long run. And remember, you can always start with REST and add GraphQL later if needed.

Environment Config the Clean Way

Stack Horizon — Fri, 14 Aug 2026 16:08:12 +0000

Stop Hardcoding: Start with a Config Layer

Every app needs configuration. API keys, database URLs, feature flags, ports. The lazy way is to sprinkle process.env calls directly in your business logic. That works until you need to test, share config across services, or change a value without redeploying. The clean way is to centralize config into a single, typed, validated module.

The Problem with Raw `process.env`

Raw environment variables are strings, untyped, and often missing. If you access process.env.PORT and it's undefined, you get a runtime crash later, not a clear error at startup. Also, you can't easily provide defaults or validate that required keys exist. And when you have 20 variables, your code becomes a mess of process.env.SOMETHING scattered everywhere.

The Clean Pattern: Config Module

Create a dedicated config module that reads all environment variables once, applies defaults, validates, and exports a frozen object. Your app imports this object instead of touching process.env directly.

Here's a minimal Node.js example using plain JavaScript:

// config/index.js
const required = ["DATABASE_URL", "API_KEY"];

function loadConfig() {
  const config = {
    port: parseInt(process.env.PORT, 10) || 3000,
    databaseUrl: process.env.DATABASE_URL,
    apiKey: process.env.API_KEY,
    isDev: process.env.NODE_ENV !== "production",
  };

  // Validate required fields
  for (const key of required) {
    if (!config[key]) {
      throw new Error(`Missing required environment variable: ${key}`);
    }
  }

  // Freeze to prevent accidental mutation
  return Object.freeze(config);
}

export const config = loadConfig();

Now in your app:

import { config } from "./config/index.js";

console.log(`Server listening on port ${config.port}`);

Benefits You Get Immediately

Early failure: Missing required variables throw at startup, not at 3am.
Type coercion: Parse integers, booleans, JSON once in one place.
Defaults: Provide sensible fallbacks.
Testability: In tests, you can override the config module or pass a mock.
Single source of truth: Change a variable name? Update one file.

Adding TypeScript for Extra Safety

If you're using TypeScript, define an interface for your config:

// config/index.ts
interface Config {
  port: number;
  databaseUrl: string;
  apiKey: string;
  isDev: boolean;
}

const loadConfig = (): Config => {
  // ... same logic
  return Object.freeze(config);
};

export const config: Config = loadConfig();

Now you get autocompletion and compile-time checks. No more typos like config.databaseurl.

Handling Nested Config and Secrets

For more complex apps, consider grouping related variables into nested objects:

const config = {
  server: {
    port: parseInt(process.env.PORT, 10) || 3000,
    host: process.env.HOST || "0.0.0.0",
  },
  db: {
    url: process.env.DATABASE_URL,
    poolSize: parseInt(process.env.DB_POOL_SIZE, 10) || 10,
  },
};

For secrets, never log them. Keep them out of your config object's toString or inspect output. Use a dedicated secrets manager in production, but for local dev, .env files are fine.

Loading `.env` Files Cleanly

Use dotenv to load .env into process.env, but do it in your config module before reading variables:

import dotenv from "dotenv";
dotenv.config();

This keeps the loading logic in one place. In production, your orchestrator (Docker, Kubernetes) sets real env vars, and dotenv simply does nothing if no .env file exists.

Testing with Config

Because your config is a module, you can mock it in tests. For example, with Jest:

jest.mock("./config", () => ({
  config: { port: 1234, databaseUrl: "mock", apiKey: "test" },
}));

Or better, design your functions to accept config as a parameter when needed. That makes pure functions easier to test.

What About Feature Flags?

Feature flags often change at runtime, not at startup. Don't put them in your static config. Use a separate dynamic config service or a simple in-memory store that can be updated. The static config is for immutable values like ports and credentials.

A Practical Checklist

[ ] Create a config module that reads all env vars.
[ ] Define defaults for optional values.
[ ] Validate required values and throw early.
[ ] Freeze the config object.
[ ] Use TypeScript interfaces for type safety.
[ ] Load .env only in the config module.
[ ] Never access process.env outside the config module.

Wrapping Up

Centralizing environment config is a small change with big payoff. It makes your app more predictable, easier to test, and less error-prone. Start with a simple module, add validation and types, and you'll thank yourself when you onboard new developers or debug a production issue. Your future self will appreciate the clean separation.

Now go refactor that process.env spaghetti.

JWT auth without the confusion

Stack Horizon — Thu, 13 Aug 2026 00:03:56 +0000

The mental model that fixes everything

JWT is just a token format. It is not authentication, not a session, and not a database. Once you separate those ideas, most of the pain disappears.

A JWT is a JSON object that is signed. That's it. The payload holds claims like sub (subject) and exp (expiration). The signature proves the token wasn't tampered with.

What JWT is not

Not a session store: You can't revoke a JWT before it expires. If you need revocation, you need a blocklist or short expiry.
Not a database: Don't stuff heavy data in the payload. It gets sent on every request.
Not a magic bullet: It's a way to pass claims between parties without a shared server-side state.

The three flows that matter

1. Access token only

Simplest flow: login returns a JWT, client sends it in the Authorization header, server verifies it on every request.

// server middleware (Express example)
const jwt = require('jsonwebtoken');

function auth(req, res, next) {
  const header = req.headers.authorization;
  if (!header) return res.status(401).json({ error: 'No token' });

  const token = header.split(' ')[1]; // Bearer <token>
  try {
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch (err) {
    res.status(401).json({ error: 'Invalid token' });
  }
}

Works fine for small apps, but every request hits your auth logic and the token can't be invalidated early.

2. Access + refresh token

Common pattern for SPAs. Access token lives 15 minutes, refresh token lives 7 days. The refresh token is stored securely (httpOnly cookie) and used only to get a new access token.

// issue tokens on login
const accessToken = jwt.sign({ userId }, process.env.JWT_SECRET, { expiresIn: '15m' });
const refreshToken = jwt.sign({ userId }, process.env.REFRESH_SECRET, { expiresIn: '7d' });

res.json({ accessToken });
res.cookie('refreshToken', refreshToken, { httpOnly: true, secure: true, sameSite: 'strict' });

Refresh endpoint:

app.post('/refresh', (req, res) => {
  const refreshToken = req.cookies.refreshToken;
  if (!refreshToken) return res.sendStatus(401);

  try {
    const payload = jwt.verify(refreshToken, process.env.REFRESH_SECRET);
    const newAccessToken = jwt.sign({ userId: payload.userId }, process.env.JWT_SECRET, { expiresIn: '15m' });
    res.json({ accessToken: newAccessToken });
  } catch {
    res.clearCookie('refreshToken');
    res.sendStatus(403);
  }
});

This gives you short-lived access tokens (less risk if leaked) and long-lived sessions without storing server-side state.

3. Stateless vs stateful

If you need to revoke tokens immediately (like on password change), you have two options:

Keep a token version in your user table. Include version in the JWT payload. Bump the version to invalidate all old tokens.
Use a blocklist (Redis or DB) for revoked tokens. Check the blocklist before verifying.

Both add state. If you don't need revocation, stay stateless.

Common mistakes I see

Storing JWT in localStorage: XSS can steal it. Use httpOnly cookies for refresh tokens, and keep access tokens in memory if possible.
Putting sensitive data in payload: It's base64 encoded, not encrypted. Anyone can read it.
Using the same secret for access and refresh: Use separate secrets. If one leaks, the other is still safe.
Not checking exp: Most libraries do it automatically, but if you hand-roll, don't forget.

The decision checklist

Ask these before adding JWT:

Do you need to revoke tokens? If yes, plan for a blocklist or versioning.
Are you building an API for multiple clients? JWT works well.
Is your server the only consumer? A simple session cookie might be easier.

Final thought

JWT is a tool, not a religion. Use it when it fits: stateless APIs, microservices, or cross-domain auth. For classic server-rendered apps, traditional sessions are often simpler. The confusion comes from mixing the token format with the auth strategy. Keep them separate and you'll be fine.

JWT auth without the confusion

Stack Horizon — Tue, 11 Aug 2026 00:01:51 +0000

JWT auth without the confusion

JWTs are everywhere, but they're often misunderstood. Let's strip away the jargon and see what they actually are, how they work, and how to use them safely in your apps.

What is a JWT?

A JWT (JSON Web Token) is just a string with three parts separated by dots:

header.payload.signature

Header: contains the algorithm and token type.
Payload: contains claims (data like user id, expiration, etc.).
Signature: used to verify the token hasn't been tampered with.

All parts are base64url encoded. The signature is created by hashing the header and payload with a secret (or private key).

How does authentication work with JWTs?

User logs in with credentials.
Server verifies credentials and creates a JWT with user info in the payload.
Server sends the token back to the client.
Client stores the token (usually in memory or localStorage) and sends it in the Authorization header for subsequent requests.
Server verifies the token's signature and expiration, then trusts the claims.

That's it. No session storage, no cookies (if you choose), no server-side state.

The classic pitfalls

1. Storing tokens in localStorage

LocalStorage is accessible to any JavaScript running on your page, making it vulnerable to XSS. If an attacker injects script, they can steal the token.

Better: use httpOnly cookies, which are not accessible to JavaScript. But then you need CSRF protection.

2. Not checking expiration

Always check exp claim. Use a library that validates it automatically.

3. Putting sensitive data in the payload

The payload is base64 encoded, not encrypted. Anyone can decode it. Never put passwords, credit card numbers, or other secrets in there.

4. Using a weak secret

If you use HS256 (symmetric), the secret must be long and random. For production, prefer RS256 (asymmetric) with a private/public key pair.

Minimal working example (Node.js + Express)

Here's a simple implementation using jsonwebtoken:

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

const SECRET = process.env.JWT_SECRET || 'change-me';

app.use(express.json());

app.post('/login', (req, res) => {
  const { username, password } = req.body;
  // Check credentials (pseudo)
  if (username === 'admin' && password === 'secret') {
    const token = jwt.sign({ sub: username }, SECRET, { expiresIn: '1h' });
    res.json({ token });
  } else {
    res.status(401).json({ error: 'Invalid credentials' });
  }
});

function authMiddleware(req, res, next) {
  const header = req.headers.authorization;
  if (!header || !header.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token' });
  }
  const token = header.slice(7);
  try {
    const payload = jwt.verify(token, SECRET);
    req.user = payload;
    next();
  } catch (err) {
    res.status(401).json({ error: 'Invalid token' });
  }
}

app.get('/protected', authMiddleware, (req, res) => {
  res.json({ message: 'You are authenticated', user: req.user });
});

app.listen(3000);

This is a minimal but functional flow.

When to use JWT vs sessions

JWT is great for:

Stateless APIs, especially microservices.
Mobile apps where cookies are tricky.
Single sign-on across domains.

Sessions (server-side storage) might be better if:

You need to revoke tokens instantly (JWTs are valid until they expire unless you maintain a blocklist).
You have simple, single-server apps.

Security checklist

Use HTTPS in production.
Set short expiration times (e.g., 15 minutes) and use refresh tokens.
Validate the aud and iss claims if using third-party auth.
Keep the secret or private key out of source code.
Use established libraries, don't roll your own crypto.

Final thoughts

JWT is not magic. It's a signed token that lets you trust the data it carries. Understand what it does and doesn't protect you from, and you'll avoid most common mistakes. Start with a simple flow, then add refresh tokens and secure storage as your app grows.

Happy coding.

API Pagination Patterns: Offset, Cursor, and Keyset Explained

Stack Horizon — Fri, 07 Aug 2026 08:00:24 +0000

Pagination is not one-size-fits-all

Every API that returns a list eventually needs pagination. The naive approach of ?page=1&limit=20 works for small datasets, but as your data grows, you'll hit performance cliffs and consistency issues. Let's break down the three main patterns, when to use them, and the tradeoffs.

Offset pagination (the classic)

GET /items?offset=40&limit=20

Offset pagination uses offset (how many records to skip) and limit (how many to return). It's easy to implement, and most developers understand it immediately.

app.get('/items', (req, res) => {
  const offset = parseInt(req.query.offset) || 0;
  const limit = Math.min(parseInt(req.query.limit) || 20, 100);
  const items = db.query('SELECT * FROM items ORDER BY id LIMIT ? OFFSET ?', [limit, offset]);
  res.json({ items, offset, limit });
});

Pros:

Simple to implement and reason about.
Works well for small to medium datasets.
Easy to jump to any page directly.

Cons:

Deep offsets are slow: the database scans and discards rows before the offset.
Inconsistent under concurrent writes: if a new record is inserted, the same offset can return duplicates or miss records.
Not ideal for real-time feeds or infinite scroll.

Cursor pagination (the modern standard)

GET /items?limit=20&cursor=eyJpZCI6MTAwfQ

Instead of counting rows, you pass an opaque cursor that encodes the position of the last item you saw. The server decodes it and queries WHERE id > cursor_id.

app.get('/items', (req, res) => {
  const limit = Math.min(parseInt(req.query.limit) || 20, 100);
  const cursor = req.query.cursor ? Buffer.from(req.query.cursor, 'base64').toString() : null;
  const cursorId = cursor ? JSON.parse(cursor).id : 0;
  const items = db.query('SELECT * FROM items WHERE id > ? ORDER BY id ASC LIMIT ?', [cursorId, limit]);
  const nextCursor = items.length === limit ? Buffer.from(JSON.stringify({ id: items[items.length - 1].id })).toString('base64') : null;
  res.json({ items, nextCursor });
});

Pros:

Fast regardless of page depth: the database uses the index on id to find the starting point.
Consistent: new records inserted between requests don't cause duplicates or skips.
Great for infinite scroll and real-time data.

Cons:

Can't jump to a specific page number.
Cursor encoding adds complexity (though libraries help).
Requires a stable, unique sort key (usually id or a timestamp).

Keyset pagination (the efficient cousin)

Keyset pagination is similar to cursor but uses the actual column values instead of an opaque token. It's often used with composite keys.

GET /items?after_id=100&after_created_at=2023-01-01T00:00:00Z&limit=20

SELECT * FROM items 
WHERE (created_at, id) > (?, ?) 
ORDER BY created_at, id 
LIMIT ?

Pros:

Very efficient, uses composite indexes.
No encoding/decoding overhead.
Transparent for debugging.

Cons:

Requires the client to understand the sort columns.
Exposes implementation details.
More complex to implement correctly, especially with multiple sort fields.

Which one should you use?

Offset: fine for admin panels, small datasets, or when you need page numbers. Avoid for public APIs with large data.
Cursor: best default for most public APIs, especially for feeds or lists that change frequently.
Keyset: good when you need maximum performance and control, and you're okay with exposing sort fields.

Practical tips

Always cap the limit to prevent abuse (e.g., max 100).
Include a next link in your response so clients don't have to construct URLs themselves.
For cursor pagination, encode the cursor as base64 or a signed token to prevent tampering.
If you need both page numbers and consistency, consider a hybrid: use cursor internally, but expose page numbers for navigation.
Document your pagination clearly: clients need to know what parameters to send and what to expect back.

A simple response envelope

{
  "data": [ ... ],
  "pagination": {
    "next": "/items?cursor=abc123",
    "prev": null,
    "total": null
  }
}

Note: total is often omitted with cursor pagination because counting all rows defeats the performance benefit. If you need totals, use a separate endpoint or a lightweight count query.

Final thoughts

Pagination is a small part of your API, but getting it wrong can cause production outages and frustrated clients. Start with cursor pagination for new endpoints. It's the safest choice for performance and consistency. If you're maintaining a legacy API with offset, consider migrating gradually, starting with the endpoints that have the most traffic.

Remember: the best pattern is the one that fits your data access patterns and client needs. There's no universal answer, but now you have the tools to make an informed decision.

Debugging Node.js Like a Pro

Stack Horizon — Wed, 05 Aug 2026 16:00:26 +0000

Start with the Built-in Inspector

Before reaching for external tools, remember Node.js has a built-in debugger. Run your script with --inspect and open chrome://inspect in Chrome to get a full DevTools experience: breakpoints, step-through, console, and even memory profiling.

node --inspect app.js

For a quick breakpoint without touching the browser, use --inspect-brk to pause on the first line. This is great for debugging startup issues.

Use `debugger` Statements and Conditional Breakpoints

Sometimes you need a breakpoint only when a condition is true. Instead of littering your code with if blocks, set a conditional breakpoint in DevTools. Right-click the line number, choose "Add conditional breakpoint," and enter an expression like user.id === 42.

For quick inline debugging, debugger; works but remember to remove it before committing. I often use it temporarily when I'm too lazy to open the DevTools UI.

Log Like a Pro with `util.inspect`

console.log of an object prints [object Object] which is useless. Use util.inspect with depth and colors to see nested structures clearly.

const util = require('util');
console.log(util.inspect(myObject, { showHidden: false, depth: null, colors: true }));

Or in modern Node, you can use console.dir with { depth: null } for the same effect.

Async Stack Traces: Don't Lose the Context

Async errors are painful because stack traces often end at the event loop. Node 12+ gives you better async stack traces by default, but you can improve them further by using Error.captureStackTrace in your own error classes.

class MyError extends Error {
  constructor(message) {
    super(message);
    Error.captureStackTrace(this, MyError);
  }
}

This makes the stack trace point to the caller, not the constructor.

Handle Unhandled Rejections and Exceptions

Silent failures are the worst. Set up global handlers to log errors properly and exit gracefully.

process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
  // Decide whether to crash or continue
});

process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', err);
  // For production, you might want to clean up and exit
});

Use `--trace-warnings` and `--trace-deprecation`

When upgrading dependencies, warnings tell you about deprecated APIs. Run with --trace-warnings to see exactly where the warning originates. --trace-deprecation gives you stack traces for deprecated calls, saving you hours of hunting.

node --trace-deprecation app.js

Debug Memory Leaks with Heap Snapshots

If your app's memory grows over time, take heap snapshots in Chrome DevTools (Memory tab). Compare two snapshots taken at different times to see which objects are accumulating. Look for closures that capture large variables or event listeners that are never removed.

Profile CPU Usage

Use the built-in profiler to find hot spots. Run with --prof and then process the output with node --prof-process.

node --prof app.js
node --prof-process isolate-*.log > profile.txt

The text file shows you which functions consume the most CPU. This is invaluable for optimizing performance.

Use `node --watch` for Development

Node 18+ includes --watch to restart on file changes. Combine it with --inspect to get auto-restart plus debugging.

node --watch --inspect app.js

Debug with Environment Variables

Make your app's behavior configurable via env vars, so you can turn on verbose logging or mock external services without code changes.

const DEBUG = process.env.DEBUG === 'true';
if (DEBUG) console.log('Detailed info');

Use libraries like debug to namespace loggers and filter them via DEBUG=app:*.

Final Thoughts

Mastering these techniques will save you countless hours. Start with the built-in inspector, learn to read stack traces properly, and don't ignore warnings. Debugging is a skill, and the more tools you have, the faster you'll find those pesky bugs.

REST vs GraphQL in Practice

Stack Horizon — Tue, 04 Aug 2026 00:01:06 +0000

The Practical Differences

When I started building APIs, REST was the default. Then GraphQL came along and promised to fix everything. After using both in real projects, I've learned that the choice isn't about which is 'better' but about what fits your use case. Let's break down the practical differences.

REST: Simple and Predictable

REST is built around resources and HTTP methods. You have endpoints like /users and /users/1. Each endpoint returns a fixed shape. It's easy to understand, cache, and debug.

Here's a typical REST call:

// Get user and their posts
const userRes = await fetch('/users/1');
const user = await userRes.json();
const postsRes = await fetch('/users/1/posts');
const posts = await postsRes.json();

Pros:

Simple to implement and consume
Built-in caching with HTTP
Great for public APIs where you control the response shape
Easy to version (/v1/users)

Cons:

Over-fetching: you get all fields even if you need one
Under-fetching: you need multiple requests to get related data
No way for the client to request exactly what it needs

GraphQL: Flexible but Complex

GraphQL gives the client control over the response. You send a query and get exactly what you ask for.

query {
  user(id: 1) {
    name
    posts {
      title
    }
  }
}

One request gets the user and their posts, with only the fields you need.

Pros:

No over-fetching or under-fetching
Single round-trip for complex data
Strongly typed schema with introspection
Great for mobile apps where bandwidth matters

Cons:

More complex to set up and maintain
Caching is harder (no natural HTTP caching)
Potential for expensive queries if not careful
Requires a learning curve for clients

Real-World Considerations

1. Team Experience

If your team knows REST well, introducing GraphQL adds a lot of new concepts: resolvers, schema, fragments, mutations. For a small internal API, REST is often easier.

2. Client Needs

If your clients are mostly web apps with simple data needs, REST is fine. If you have mobile clients with variable network conditions, GraphQL's ability to fetch exactly what's needed is a big win.

3. Performance

REST can be faster for simple requests because of HTTP caching and CDN support. GraphQL can be slower if you have deeply nested queries, but you can mitigate with query complexity limits and DataLoader for batching.

4. Tooling

REST has mature tooling: Swagger, Postman, caching proxies. GraphQL has excellent tools like Apollo and GraphiQL, but they are more complex to set up.

A Hybrid Approach

You don't have to choose one. Many projects start with REST and add GraphQL for specific use cases. For example, you can expose a REST API for public consumption and a GraphQL API for your own frontend. This gives you the best of both worlds.

My Take

For my current project, I used REST for the public API because it's stable and easy for third parties to consume. Internally, the frontend uses GraphQL to avoid multiple round-trips. It adds some complexity, but the improved developer experience is worth it.

If you're starting fresh and your API is mostly for your own clients, GraphQL is a solid choice. If you're building a public API with unknown consumers, REST is safer.

Bottom Line

REST is like a buffet: you get a fixed plate. GraphQL is like ordering à la carte: you pick exactly what you want. Both work, but they fit different situations. Understand your requirements, your team, and your clients before choosing.

Happy coding!

JWT Auth Without the Confusion

Stack Horizon — Fri, 31 Jul 2026 00:00:57 +0000

What JWT Actually Is

JWT (JSON Web Token) is a compact, URL-safe way to transmit claims between two parties. It's not a magic security solution. It's a token format: three base64url-encoded segments separated by dots (header.payload.signature).

header: {"alg":"HS256","typ":"JWT"}
payload: {"sub":"user123","iat":1700000000}
signature: HMACSHA256(base64url(header)+"."+base64url(payload), secret)

The Common Mistake: Storing JWT in localStorage

Don't do it. localStorage is accessible via JavaScript (XSS). If an attacker injects a script, they steal your tokens. Use httpOnly cookies instead. The cookie is sent automatically with requests and is not readable by JS.

// Bad: vulnerable to XSS
localStorage.setItem('token', jwt);

// Better: httpOnly cookie (set by server)
Set-Cookie: token=<jwt>; HttpOnly; Secure; SameSite=Strict

How to Implement JWT Auth (The Practical Way)

1. Login endpoint issues a JWT in a cookie

app.post('/login', (req, res) => {
  const { username, password } = req.body;
  const user = authenticate(username, password);
  if (!user) return res.status(401).send('Invalid credentials');

  const token = jwt.sign(
    { sub: user.id, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '15m' }
  );

  res.cookie('token', token, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 15 * 60 * 1000
  });
  res.json({ message: 'Logged in' });
});

2. Middleware verifies the token on each request

function authMiddleware(req, res, next) {
  const token = req.cookies.token;
  if (!token) return res.status(401).send('No token');

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(403).send('Invalid token');
  }
}

app.get('/protected', authMiddleware, (req, res) => {
  res.json({ user: req.user });
});

3. Refresh tokens for longer sessions

Access tokens are short-lived (15 min). Use a refresh token (long-lived, stored in a separate httpOnly cookie) to get new access tokens without asking for credentials again.

app.post('/refresh', (req, res) => {
  const refreshToken = req.cookies.refreshToken;
  if (!refreshToken) return res.status(401).send('No refresh token');

  try {
    const decoded = jwt.verify(refreshToken, process.env.REFRESH_SECRET);
    const newAccessToken = jwt.sign(
      { sub: decoded.sub },
      process.env.JWT_SECRET,
      { expiresIn: '15m' }
    );
    res.cookie('token', newAccessToken, { httpOnly: true, secure: true, sameSite: 'strict' });
    res.json({ message: 'Token refreshed' });
  } catch (err) {
    return res.status(403).send('Invalid refresh token');
  }
});

What JWT Does NOT Solve

CSRF: If you use cookies, you need CSRF protection. Use SameSite=Strict or CSRF tokens.
Token revocation: JWT is stateless. You can't revoke a single token unless you maintain a blacklist (which defeats statelessness). For logout, clear the cookie on the server side or use short expiry.
Payload tampering: The signature ensures integrity. Never trust the payload without verifying the signature.

Common Pitfalls

Storing secrets in code: Use environment variables.
Using weak secrets: Use a long, random string (e.g., openssl rand -hex 64).
Not validating algorithms: If your server accepts 'none' algorithm, attackers can forge tokens. Always specify allowed algorithms.

// Explicitly set algorithms
jwt.verify(token, secret, { algorithms: ['HS256'] });

Summary

JWT is a tool, not a silver bullet. Use httpOnly cookies, short-lived tokens, refresh tokens, and proper CSRF protection. Understand the tradeoffs: statelessness vs. revocation. Keep it simple.

API Pagination Patterns: Offset vs Cursor vs Keyset

Stack Horizon — Wed, 29 Jul 2026 08:00:19 +0000

Why Pagination Matters

If you've ever built an API endpoint that returns a list, you've probably faced the question: what happens when the list has 10,000 items? Returning them all at once is a recipe for slow responses, memory exhaustion, and angry mobile users. Pagination is the answer, but not all pagination is created equal. Let's look at the three most common patterns: offset, cursor, and keyset pagination.

Offset Pagination (The Classic)

This is the simplest approach. The client sends page and per_page (or limit and offset), and the server skips that many rows.

# Flask example
@app.route('/items')
def get_items():
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 20, type=int)
    offset = (page - 1) * per_page
    items = db.execute('SELECT * FROM items ORDER BY id LIMIT ? OFFSET ?', (per_page, offset))
    return jsonify(items)

Pros:

Easy to implement and understand.
Works with any database, even in-memory lists.
Allows jumping to any page directly.

Cons:

Performance degrades with large offsets. The database still scans all skipped rows. On a table with 1 million rows, OFFSET 999980 is painfully slow.
Inconsistent results if rows are inserted/deleted. If a new row is added between requests, the same page might show different items.

Cursor Pagination (The Reliable One)

Instead of page numbers, the client passes a cursor (an opaque string) that points to the last item seen. The server returns items after that cursor.

@app.route('/items')
def get_items():
    cursor = request.args.get('cursor')
    per_page = request.args.get('per_page', 20, type=int)
    if cursor:
        # Decode cursor (e.g., base64 encoded ID)
        last_id = decode_cursor(cursor)
        items = db.execute('SELECT * FROM items WHERE id > ? ORDER BY id LIMIT ?', (last_id, per_page))
    else:
        items = db.execute('SELECT * FROM items ORDER BY id LIMIT ?', (per_page,))
    next_cursor = encode_cursor(items[-1]['id']) if len(items) == per_page else None
    return jsonify({'items': items, 'next_cursor': next_cursor})

Pros:

Fast and stable. Uses indexed columns (like id) to filter, so it scales to any offset.
Consistent. New rows don't shift pages because you always move forward from a specific point.
Real-time friendly. No duplicate or missed items when data changes.

Cons:

No random page access. You can't jump to page 5; you must traverse sequentially.
Cursor encoding adds complexity. You need to encode/decode the cursor (base64 is common).
Only works with sortable, unique fields. You need a column to order by (usually id or created_at).

Keyset Pagination (The SQL Optimized)

Similar to cursor, but uses the actual column values from the last row instead of an opaque token. Often used with composite keys.

@app.route('/items')
def get_items():
    last_id = request.args.get('last_id', type=int)
    last_created = request.args.get('last_created')
    per_page = request.args.get('per_page', 20, type=int)
    if last_id and last_created:
        items = db.execute('''
            SELECT * FROM items 
            WHERE (created_at, id) > (?, ?) 
            ORDER BY created_at, id 
            LIMIT ?
        ''', (last_created, last_id, per_page))
    else:
        items = db.execute('SELECT * FROM items ORDER BY created_at, id LIMIT ?', (per_page,))
    return jsonify({'items': items})

Pros:

Best performance. Uses database indexes efficiently, no OFFSET at all.
No cursor encoding needed. The client just passes raw column values.

Cons:

Tied to sort order. If you change the sort, the keyset changes.
Requires exposing column values. The client needs to know the last id or timestamp, which might be sensitive.
No random access. Like cursor pagination.

When to Use What

Offset pagination: Use for small datasets (under 10k rows) or when random page access is critical (e.g., admin panels).
Cursor pagination: Use for large, dynamic datasets where consistency matters (e.g., social feeds, activity logs).
Keyset pagination: Use when you need maximum performance and control over the sort order (e.g., real-time dashboards).

A Practical Compromise

Sometimes you can combine both: offer offset-based pagination for the first few pages (where performance is fine) and switch to cursor-based once the offset passes a threshold. But in most modern APIs, cursor pagination is the go-to choice. It's reliable, scalable, and the extra complexity is minimal.

Final Thought

Whichever pattern you choose, document it clearly. Your API consumers will thank you when they don't have to guess how to get the next page. And always test with large datasets to catch performance issues early.

DEV Community: Stack Horizon

REST vs GraphQL in Practice

The Real Trade-offs

REST: Predictable and Simple

GraphQL: Precise and Flexible

Performance in Practice

Tooling and Ecosystem

My Rule of Thumb

Practical Example: Both in One App

Final Thoughts

TypeScript Features Worth Adopting First

Start with the essentials, not the entire type system

1. Explicit function return types

2. unknown over any

3. Discriminated unions

4. satisfies operator (TypeScript 4.9+)

5. Readonly and readonly properties

6. Utility types: Partial, Pick, Omit

7. const assertions

8. noUncheckedIndexedAccess (strictness)

Start small, then expand

Debugging Node.js Like a Pro

Start with the Right Mindset

Use the Built-in Debugger

Debug with Chrome DevTools

Use debug for Logging

Handle Unhandled Rejections and Exceptions

Use node --trace-warnings

Inspect Memory Leaks

Use async_hooks for Async Debugging

Use --stack-trace-limit

Use util.inspect for Deep Objects

Debug with ndb (Optional)

Wrap Up

REST vs GraphQL in Practice

The Real Trade-offs

REST: The Workhorse

When REST shines

The pain points

GraphQL: The Flexible Alternative

When GraphQL shines

The hidden costs

My Decision Framework

Hybrid Approach

Practical Tips

The Verdict

Environment Config the Clean Way

Stop Hardcoding: Start with a Config Layer

The Problem with Raw process.env

The Clean Pattern: Config Module

Benefits You Get Immediately

Adding TypeScript for Extra Safety

Handling Nested Config and Secrets

Loading .env Files Cleanly

Testing with Config

What About Feature Flags?

A Practical Checklist

Wrapping Up

JWT auth without the confusion

The mental model that fixes everything

What JWT is not

The three flows that matter

1. Access token only

2. Access + refresh token

3. Stateless vs stateful

Common mistakes I see

The decision checklist

Final thought

JWT auth without the confusion

JWT auth without the confusion

What is a JWT?

How does authentication work with JWTs?

The classic pitfalls

1. Storing tokens in localStorage

2. Not checking expiration

3. Putting sensitive data in the payload

4. Using a weak secret

Minimal working example (Node.js + Express)

When to use JWT vs sessions

Security checklist

2. `unknown` over `any`

4. `satisfies` operator (TypeScript 4.9+)

5. `Readonly` and `readonly` properties

6. Utility types: `Partial`, `Pick`, `Omit`

7. `const` assertions

8. `noUncheckedIndexedAccess` (strictness)

Use `debug` for Logging

Use `node --trace-warnings`

Use `async_hooks` for Async Debugging

Use `--stack-trace-limit`

Use `util.inspect` for Deep Objects

Debug with `ndb` (Optional)

The Problem with Raw `process.env`

Loading `.env` Files Cleanly

Use `debugger` Statements and Conditional Breakpoints

Log Like a Pro with `util.inspect`

Use `--trace-warnings` and `--trace-deprecation`

Use `node --watch` for Development