DEV Community: Stack Horizon

TypeScript Features Worth Adopting First

Stack Horizon — Sat, 12 Sep 2026 16:00:57 +0000

I've onboarded a few teams onto TypeScript, and the same pattern shows up every time: people try to use everything at once. Generics everywhere, conditional types, mapped types, decorators. Then they get frustrated and blame TypeScript.

The trick is to adopt features in the order that pays off fastest. Here's the order I'd recommend, based on what actually removed bugs from my code.

1. `strict` mode in tsconfig

This isn't a feature so much as a setting, but it's the highest-value thing you can do on day one. Turn it on before you write a lot of code, because retrofitting it later is painful.

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}

strict bundles strictNullChecks, noImplicitAny, and friends. noUncheckedIndexedAccess is separate and not included in strict, but it's worth adding: it makes arr[0] return T | undefined instead of T, which catches a whole class of off-by-one crashes.

If you're migrating an existing JS codebase, you can turn these on per-directory instead of globally.

2. Union types and narrowing

This is the feature that made me stop missing dynamic languages. A union type plus a discriminant is often all you need instead of a class hierarchy.

 type Result =
  | { status: "ok"; data: string }
  | { status: "error"; message: string };

function handle(r: Result) {
  if (r.status === "ok") {
    return r.data; // TS knows data exists here
  }
  return r.message; // and message here
}

No casts, no any. The switch on r.status narrows the type automatically. I use this shape for API responses, form state, and reducers constantly.

3. `unknown` instead of `any`

any turns off type checking for everything it touches. unknown is the safe version: you can assign anything to it, but you have to narrow it before using it.

function parseJSON(input: string): unknown {
  return JSON.parse(input);
}

const data = parseJSON(raw);
// data.foo // error: object is of type 'unknown'

if (typeof data === "object" && data !== null && "id" in data) {
  console.log(data.id);
}

Use unknown at every boundary where data comes from outside your program: JSON.parse, fetch, localStorage, message handlers. Then write a small type guard to narrow it.

4. Type guards and `satisfies`

A user-defined type guard is just a function with a value is Type return annotation.

function isUser(v: unknown): v is { id: number; name: string } {
  return (
    typeof v === "object" &&
    v !== null &&
    "id" in v &&
    typeof (v as any).id === "number"
  );
}

Once you have guards, satisfies (added in TS 4.9) becomes useful. It checks a value against a type without widening it:

const routes = {
  home: "/",
  about: "/about",
} satisfies Record<string, `/${string}`>;

// routes.home is still typed as "/", not string

I reach for satisfies on config objects where I want both validation and literal types preserved.

5. Utility types you'll actually use

You don't need to learn all of them. Start with four:

Partial<T> for update payloads
Pick<T, K> and Omit<T, K> for DTOs derived from a domain model
Record<K, V> for lookup maps
ReturnType<typeof fn> for inferring types from existing functions

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

type UserUpdate = Partial<Pick<User, "name" | "email">>;
type PublicUser = Omit<User, "email">;

Deriving types from a single source of truth beats hand-writing parallel interfaces that drift apart.

What to skip for now

Conditional types, template literal type gymnastics, and heavy generic abstractions are powerful but rarely worth the readability cost in application code. They shine in library code where you're writing the abstraction once and consuming it many times. In an app, they mostly confuse the next person reading the file.

The order that works

strict and noUncheckedIndexedAccess
Union types with discriminants
unknown at boundaries
Type guards and satisfies
The four utility types above

Get comfortable with these five and you'll catch the majority of runtime bugs TypeScript is good at preventing. The advanced stuff can wait until you have a concrete problem it solves.

Database Indexing That Actually Speeds Things Up

Stack Horizon — Fri, 11 Sep 2026 08:00:49 +0000

Most slow queries I have debugged were not caused by missing indexes. They were caused by indexes that existed but could not be used. The index was there, the query was slow, and nobody connected the two. Here is how I think about making an index actually do its job.

The index only helps if the query can use it

A B-tree index on users(email) lets the database jump straight to a row instead of scanning the table. But the moment you wrap the column in a function or an expression, that ability disappears:

-- index on email is ignored here
SELECT * FROM users WHERE lower(email) = 'a@b.com';

The planner sees lower(email), not email, so it falls back to a sequential scan. Two fixes:

-- option 1: match the expression
CREATE INDEX idx_users_lower_email ON users (lower(email));

-- option 2: store the value already normalized
-- (and index the plain column)
SELECT * FROM users WHERE email = 'a@b.com';

This is the single most common reason an index sits unused. Arithmetic, casts, and COALESCE cause the same problem.

Column order in a composite index matters

For CREATE INDEX ON orders (customer_id, created_at), the index is sorted by customer_id first, then created_at. That means:

WHERE customer_id = 42 uses it.
WHERE customer_id = 42 AND created_at > '2024-01-01' uses it and is fast.
WHERE created_at > '2024-01-01' alone does not, because created_at is not the leading column.

The rule I use: put equality columns first, range columns last. If a query filters on a range across several columns, only the leading range column gets the fast seek; the rest become a filter on top.

Covering indexes avoid the table lookup

A normal index finds the row, then the database reads the table to get the rest of the columns. If the index already contains everything the query needs, that second step disappears. In Postgres you can include extra columns:

CREATE INDEX idx_orders_customer_covering
  ON orders (customer_id) INCLUDE (total, status);

SELECT total, status FROM orders WHERE customer_id = 42;

This is a real win on hot read paths. The tradeoff is a bigger index and slower writes, so I only do it when I have measured the read cost.

Selectivity decides whether it is worth it

An index on a boolean column with a 50/50 split is nearly useless. The planner will often choose a sequential scan anyway, because reading half the table through an index is slower than reading the table directly. Indexes pay off when the condition matches a small fraction of rows. Before adding one, ask how many rows a typical query returns versus how many exist.

Verify with the plan, not with hope

Never assume an index is used. Check:

EXPLAIN ANALYZE
SELECT total FROM orders WHERE customer_id = 42;

Look for Index Scan or Index Only Scan versus Seq Scan. Index Only Scan means the covering index did its job. If you see a sequential scan on a large table, the index is not being applied and you now know to look at the expression or column order.

A few habits that keep indexes honest

Index the columns in your WHERE, JOIN, and ORDER BY clauses, not every column you can think of.
Every index adds write cost. A table with ten indexes is slow to insert into.
Drop indexes nobody uses. Postgres tracks usage in pg_stat_user_indexes.
Rebuild or reindex after large deletes if the planner starts misjudging row counts.

Indexing is not about adding more indexes. It is about shaping the query and the index so the planner can actually use one. Match the expression, order the columns for the filter pattern, cover the read when it pays off, and confirm with EXPLAIN. That sequence fixes more slow queries than any amount of guessing.

API Pagination Patterns: Offset, Cursor, and Keyset Explained

Stack Horizon — Wed, 09 Sep 2026 08:00:31 +0000

API Pagination Patterns: Offset, Cursor, and Keyset Explained

If you've built or consumed APIs, you've hit the moment where a list endpoint returns everything at once. That works until it doesn't. Pagination is how you keep responses fast, memory low, and clients sane. Let's look at the three common patterns and when each makes sense.

Offset Pagination

The simplest approach: ?page=2&limit=20 or ?offset=40&limit=20. The server skips offset rows and returns limit rows.

SELECT * FROM posts ORDER BY id LIMIT 20 OFFSET 40;

Pros:

Easy to implement and understand.
Clients can jump to any page directly.
Works fine for small datasets or static data.

Cons:

Performance degrades on large offsets because the database still scans all skipped rows.
If new rows are inserted or deleted between requests, you get duplicates or missing items (unstable results).

Use it for admin panels, internal tools, or when your dataset is small and mostly static.

Cursor Pagination

Cursor pagination uses an opaque token that points to a specific item. The client sends ?cursor=abc123&limit=20, and the server returns items after that cursor, plus the next cursor (if any).

{
  "data": [/* items */],
  "next_cursor": "xyz789"
}

How it works server-side:

SELECT * FROM posts WHERE id > :cursor_id ORDER BY id LIMIT 20;

The cursor is often an encoded version of the last item's sort key (e.g., Base64(id)).

Pros:

Stable: even if new items are added, you won't see duplicates or miss items.
Fast on large datasets because it uses indexed range queries, not offsets.

Cons:

Clients can't jump to a specific page number (but do they really need to?).
Slightly more complex to implement.

This is the go-to for real-time feeds, activity logs, or any high-volume data that changes often.

Keyset Pagination

Keyset pagination is a specific type of cursor where the cursor is the actual value of the sort column(s). For example, ?after_id=100&limit=20. It's similar to cursor but transparent.

SELECT * FROM posts WHERE id > 100 ORDER BY id LIMIT 20;

Pros:

Simple to reason about and debug.
Same performance benefits as cursor if the sort column is indexed.

Cons:

Requires a unique, sortable key (often the primary key).
If you sort by something non-unique (e.g., created_at), you need a tiebreaker like id to avoid missing rows.

Many APIs implement cursor as keyset under the hood; the difference is mostly in how you expose it.

Choosing the Right Pattern

Here's my rule of thumb:

Small or static data: offset pagination is fine. Don't over-engineer.
Large, dynamic data: use cursor or keyset. Your database will thank you.
Need random access to pages: offset is the only option, but consider capping the offset (e.g., max 10,000) to avoid performance cliffs.

Also think about the client. Mobile apps often prefer infinite scroll, which fits cursors perfectly. Web dashboards with page numbers might want offset.

Real-World Example: Building a Simple Cursor

Let's say you have a posts table with an auto-increment id. Your endpoint could look like this (pseudo-code):

from flask import request, jsonify

@app.route('/api/posts')
def get_posts():
    limit = int(request.args.get('limit', 20))
    cursor = request.args.get('cursor')

    query = Post.query.order_by(Post.id.asc()).limit(limit + 1)
    if cursor:
        query = query.filter(Post.id > int(cursor))

    posts = query.all()
    has_more = len(posts) > limit
    posts = posts[:limit]

    next_cursor = posts[-1].id if has_more else None
    return jsonify({
        'data': [p.to_dict() for p in posts],
        'next_cursor': next_cursor
    })

Notice I fetch limit + 1 to know if there's a next page. That's a common trick.

Final Thoughts

Pagination is more than just adding limit and offset. It affects performance, consistency, and client experience. Start with offset if you're prototyping, but switch to cursor or keyset as soon as you expect real traffic. Your future self (and your API consumers) will appreciate it.

For more depth, check out the MDN guide on pagination (not exactly, but good for web APIs) or the JSON:API spec on pagination. Both are canonical references worth bookmarking.

Debugging Node.js Like a Pro

Stack Horizon — Sat, 05 Sep 2026 16:00:31 +0000

Start with the Built-in Inspector

Before reaching for external tools, remember Node.js ships with a powerful debugger. Run your script with --inspect and open chrome://inspect in Chrome (or any Chromium browser). You get breakpoints, step-through, watch expressions, and the console right there.

node --inspect app.js

For an even easier start, use --inspect-brk to pause on the first line so you can set breakpoints before any code runs.

node --inspect-brk app.js

Use the Debugger Statement

Sometimes you want a quick breakpoint without touching the browser. Drop a debugger; statement in your code. When you run with --inspect, execution pauses there automatically.

function calculateTotal(items) {
  debugger; // pause here
  return items.reduce((sum, item) => sum + item.price, 0);
}

This is perfect for a quick look at variables without setting up formal breakpoints.

Async Debugging with AsyncLocalStorage

Async code is where bugs hide. The context gets lost across promises and callbacks. AsyncLocalStorage from node:async_hooks lets you track request IDs or user context across async boundaries.

const { AsyncLocalStorage } = require('node:async_hooks');
const storage = new AsyncLocalStorage();

function log(message) {
  const context = storage.getStore();
  console.log(`[${context?.requestId ?? 'no-id'}] ${message}`);
}

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

Now your logs carry context even when async operations interleave. You'll spot which request caused the error.

Read the Stack Trace Properly

Node stack traces can be noisy. Use the --stack-trace-limit flag to increase the number of frames shown.

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

But more importantly, filter out internal Node modules. Look for the first line that references your own code. That's where the bug is, not in node:internal files.

Handle Unhandled Rejections Explicitly

Silent promise rejections are the worst. In modern Node (>=15), unhandled rejections crash by default, but you might still miss the root cause if you don't log properly.

process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
  process.exit(1);
});

Add this early in your app and you'll catch the exact promise that failed.

Use Logging Levels, Not Just console.log

console.log is fine for quick checks, but for real debugging you need levels. Use pino or winston. They give you timestamps, levels, and structured output that you can grep.

const pino = require('pino');
const logger = pino({ level: process.env.LOG_LEVEL || 'info' });

logger.debug('Entering function');
logger.info({ userId: 123 }, 'User logged in');
logger.error({ err }, 'Failed to save');

Then run with LOG_LEVEL=debug when you need more detail, without changing code.

Debug Memory Leaks with Heap Snapshots

If your app's memory grows over time, take heap snapshots. Run your app with --inspect, then in Chrome DevTools go to the Memory tab and take a snapshot. Compare two snapshots taken at different times to see what objects are accumulating.

You can also trigger a snapshot programmatically:

const inspector = require('node:inspector');
const fs = require('node:fs');

function takeSnapshot() {
  const session = new inspector.Session();
  session.connect();
  session.post('HeapProfiler.takeHeapSnapshot', (err, { result }) => {
    if (err) return console.error(err);
    fs.writeFileSync('heap.heapsnapshot', result.data);
    session.disconnect();
  });
}

Profile CPU Usage

Node's built-in profiler gives you a CPU profile without extra dependencies.

node --prof app.js

This writes a .log file. Then process it:

node --prof-process isolate-*.log > processed.txt

Open the processed file and look for functions with high self-time. Those are your hot spots.

Test With Realistic Input

Many bugs only appear with real data. Use fixtures that mimic production. If you're dealing with JSON, use JSON.parse with a try-catch to see malformed data.

try {
  const data = JSON.parse(raw);
} catch (err) {
  console.error('Bad JSON:', raw.slice(0, 200)); // log a snippet
}

The Power of `--trace-warnings`

Deprecation warnings can be silent. Run with --trace-warnings to see where they originate.

node --trace-warnings app.js

This often reveals outdated API usage that will break in future versions.

Wrap Up

Debugging is a skill. Start with the built-in inspector for step-by-step, use AsyncLocalStorage for async context, and get comfortable with stack traces and heap snapshots. Add structured logging early, and you'll spend less time guessing and more time fixing.

Remember: the best debugging is the kind you avoid by writing clear, testable code. But when bugs do appear, these tools will help you find them fast.

JWT Auth Without the Confusion

Stack Horizon — Fri, 04 Sep 2026 08:00:30 +0000

The Problem with JWT Tutorials

Most JWT tutorials dump a ton of theory on you: signatures, algorithms, refresh tokens, and where to store them. By the end, you're more confused than when you started. I've been there. So let's strip it down to what actually matters and build a simple, working JWT auth flow.

What JWT Actually Is

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

header.payload.signature

Header: tells the server what algorithm was used to sign it (usually HS256).
Payload: contains claims like userId, exp, and iat.
Signature: a hash of the header and payload using a secret key. This is what prevents tampering.

The key point: the token is signed, not encrypted. Anyone can decode the payload, but they can't modify it without invalidating the signature.

The Flow in Plain English

User logs in with username and password.
Server verifies credentials and creates a token containing the user's ID and an expiration time.
Server sends the token back to the client.
Client stores the token (usually in memory or localStorage).
Client sends the token in the Authorization header on every request.
Server verifies the token's signature and expiration, then reads the user ID from the payload.

That's it. No sessions, no cookies, no server-side storage.

Minimal Node.js Implementation

Let's build a tiny Express server with two routes: /login and /profile. We'll use the jsonwebtoken package.

npm install express jsonwebtoken

Here's the complete server:

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

const app = express();
app.use(express.json());

const SECRET = 'your-secret-key';

// Dummy user database
const users = [{ id: 1, username: 'alice', password: 'secret' }];

// Login route
app.post('/login', (req, res) => {
  const { username, password } = req.body;
  const user = users.find(u => u.username === username && u.password === password);
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  const token = jwt.sign({ userId: user.id }, SECRET, { expiresIn: '1h' });
  res.json({ token });
});

// Protected route
app.get('/profile', (req, res) => {
  const authHeader = req.headers.authorization;
  if (!authHeader) {
    return res.status(401).json({ error: 'No token provided' });
  }

  const token = authHeader.split(' ')[1]; // Remove 'Bearer '
  try {
    const payload = jwt.verify(token, SECRET);
    const user = users.find(u => u.id === payload.userId);
    res.json({ username: user.username });
  } catch (err) {
    res.status(401).json({ error: 'Invalid or expired token' });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Client-Side Usage (Fetch)

On the client, after login, store the token and attach it to requests:

// Login
const res = await fetch('/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'alice', password: 'secret' })
});
const { token } = await res.json();
localStorage.setItem('token', token);

// Fetch profile
const profileRes = await fetch('/profile', {
  headers: { 'Authorization': `Bearer ${localStorage.getItem('token')}` }
});
const profile = await profileRes.json();
console.log(profile); // { username: 'alice' }

Common Mistakes and How to Avoid Them

1. Storing Secrets in Client Code

Never put your JWT secret in the client. It's only used on the server to sign and verify. If it leaks, anyone can forge tokens.

2. Not Checking Expiration

The jsonwebtoken library checks exp automatically. If you roll your own, don't forget to validate it. A token that never expires is a security hole.

3. Putting Sensitive Data in the Payload

The payload is base64-encoded, not encrypted. Don't put passwords or credit card numbers in there. Just the user ID and maybe a role.

4. Using `localStorage` for High-Security Apps

localStorage is accessible to any JavaScript on the page, making it vulnerable to XSS. For highly sensitive apps, consider storing tokens in memory or using httpOnly cookies. For most tutorials and small projects, localStorage is fine.

When JWT Makes Sense

Stateless APIs: you don't want to manage session storage.
Microservices: each service can verify tokens independently.
Mobile apps: tokens work well with native clients.

When to Avoid It

Server-rendered apps with sessions: traditional cookies are simpler and more secure.
Short-lived, high-frequency requests: token verification adds CPU overhead, though it's usually negligible.

Final Thoughts

JWT is not magic. It's a signed piece of data that lets your server trust requests without storing session state. Once you understand the three parts and the simple flow, you can implement it in any language. Start small, test with a tool like Postman, and then expand to refresh tokens and logout blacklists if you need them.

Now go build something without the confusion.

async/await without the pitfalls

Stack Horizon — Wed, 02 Sep 2026 00:00:32 +0000

async/await without the pitfalls

Async/await is the bread and butter of modern JavaScript. It makes asynchronous code look synchronous, which is great for readability. But it comes with its own set of footguns that can bite you in production. Here's how to avoid them.

Pitfall 1: Forgetting `await` in a loop

You might write something like this, expecting each request to finish before the next starts:

async function fetchAll(urls) {
  const results = [];
  for (const url of urls) {
    const res = await fetch(url); // this is fine, but see below
    results.push(await res.json());
  }
  return results;
}

That's actually correct. The issue arises when you forget await inside a .map() or .forEach():

// Wrong: map returns an array of promises, not data
const data = urls.map(async (url) => {
  const res = await fetch(url);
  return res.json();
});
// data is now an array of promises, not the JSON data

async functions always return a promise. So if you use map with an async callback, you get an array of promises. To fix it, use Promise.all:

const data = await Promise.all(urls.map(async (url) => {
  const res = await fetch(url);
  return res.json();
}));

But beware: Promise.all fails fast. If one request fails, the whole thing rejects. If you need to handle failures individually, use Promise.allSettled instead.

Pitfall 2: Swallowing errors silently

A common mistake is to catch an error and do nothing, which makes debugging a nightmare:

try {
  const data = await fetchData();
  // process data
} catch (error) {
  // do nothing? bad!
}

Always at least log the error. Even better, handle it gracefully or rethrow it:

try {
  const data = await fetchData();
} catch (error) {
  console.error('Failed to fetch data:', error);
  throw error; // rethrow if you want the caller to handle it
}

If you're using async/await, unhandled promise rejections can crash your app in Node.js. Always have a catch or a global handler.

Pitfall 3: Sequential execution when you need parallel

Using await inside a loop makes requests run one after another. If they're independent, that's a performance hit:

// Slow: sequential
for (const id of ids) {
  const user = await getUser(id);
  console.log(user);
}

// Fast: parallel
const users = await Promise.all(ids.map(getUser));
users.forEach(console.log);

But don't go overboard. Parallel requests can overwhelm a server or hit rate limits. A good middle ground is to batch them with Promise.all in chunks.

Pitfall 4: Using `async` when you don't need it

If a function doesn't have await inside, making it async is unnecessary and can cause subtle issues:

// Unnecessary async
async function double(x) {
  return x * 2;
}
// This returns a promise, so you need to await it even though it's sync

It also changes error handling. If you throw inside an async function, it becomes a rejected promise, not a synchronous exception. Only use async when you actually await something.

Pitfall 5: Ignoring cancellation

Async/await doesn't have built-in cancellation. If you start a fetch and the user navigates away, you might still update the UI or leak resources. A simple pattern is to use an AbortController:

const controller = new AbortController();
try {
  const res = await fetch(url, { signal: controller.signal });
  // ...
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request aborted');
  } else {
    throw error;
  }
}
// To cancel:
controller.abort();

For more complex scenarios, libraries like p-cancelable exist, but sometimes a simple flag works:

let isCancelled = false;
async function longTask() {
  while (!isCancelled) {
    // do work
  }
}

Pitfall 6: Forgetting that `await` blocks the event loop

await doesn't block the event loop, but it does pause the function. If you have a long-running synchronous operation inside an async function, it will block everything else. For CPU-heavy tasks, use setImmediate or worker threads to yield control.

Final tips

Always use try/catch or .catch() on every promise you create.
Prefer Promise.allSettled when you need to handle partial failures.
Use Promise.race for timeouts, but be careful about unhandled rejections from the losing promise.
Lint your code with rules that catch missing await (like require-await in ESLint).

Async/await is a powerful tool, but it's not magic. Understand these pitfalls, and you'll write more robust asynchronous code.

Happy coding!

API Pagination Patterns: Choosing the Right Approach

Stack Horizon — Sat, 29 Aug 2026 08:00:34 +0000

API Pagination Patterns: Choosing the Right Approach

Pagination is one of those things you don't think about until your API grows. Then suddenly your endpoints are returning thousands of records, mobile clients are crawling, and the database is sweating. I've built and consumed enough APIs to know that picking the right pagination pattern early saves a lot of pain. Let's walk through the common options, their trade-offs, and when to use each.

Offset Pagination (The Classic)

This is the simplest: ?page=2&limit=20 or ?offset=40&limit=20. The server skips a number of rows and returns the next set.

SELECT * FROM items ORDER BY id LIMIT 20 OFFSET 40;

Pros:

Easy to implement, works everywhere.
Clients can jump to any page directly.
Stateless, no extra server logic.

Cons:

Performance degrades with large offsets because the database still scans and discards rows.
Inconsistent results if new items are inserted between requests (you might see duplicates or miss rows).

I use offset pagination for small datasets or internal admin tools where consistency isn't critical. For public APIs, I'd think twice.

Cursor-Based Pagination (Keyset)

Instead of a page number, the client sends a cursor that points to the last item from the previous page. The server returns rows after that cursor.

SELECT * FROM items WHERE id > :last_id ORDER BY id LIMIT 20;

Response includes a next_cursor field:

{
  "data": [ ... ],
  "next_cursor": "eyJpZCI6MTAwfQ"
}

The cursor is often an opaque string (base64 encoded JSON) or just the last ID.

Pros:

Scales well: no matter how deep you paginate, the query uses an index.
Stable results even if new items are added, because you're always moving forward from a fixed point.

Cons:

Can't jump to a specific page number.
Requires a unique, sortable column (usually the primary key).
Slightly more complex to implement.

This is my go-to for most read-heavy APIs, especially feeds, timelines, and any list that grows over time.

Keyset with Composite Cursors

When you need to sort by something other than the ID, like created_at, you need a composite cursor. The cursor encodes both the sort key and the ID to break ties.

SELECT * FROM items 
WHERE (created_at, id) > (:last_created_at, :last_id) 
ORDER BY created_at, id LIMIT 20;

Make sure you have a composite index on (created_at, id) for this to be fast. I've seen people forget that and wonder why their query is slow.

Page-Based with a Token (Offset + Cursor Hybrid)

Some APIs return a token that encodes the offset, but also include a checksum or snapshot ID to detect changes. This is rare and often over-engineered. I'd avoid it unless you have a specific need.

Limit/Offset with a Stable Sort

If you must use offset pagination, at least make it consistent by ordering by a unique column and using a transaction snapshot (if your database supports it). But honestly, that's a band-aid.

Time-Based Pagination

For time-series data, you can paginate by time windows: ?before=2024-01-01T00:00:00Z. It's a form of keyset where the cursor is a timestamp.

SELECT * FROM events WHERE occurred_at < :cursor ORDER BY occurred_at DESC LIMIT 20;

Works well for logs, metrics, or any append-only data. Just be careful with duplicate timestamps; add a secondary sort key like ID.

What About GraphQL?

GraphQL often uses Relay-style connections with cursors. That's essentially cursor pagination with a standardized format. If you're building a GraphQL API, you'll likely adopt that pattern anyway.

Choosing What to Return

Regardless of the pattern, your response should include metadata:

{
  "data": [...],
  "pagination": {
    "next_cursor": "...",
    "has_more": true
  }
}

For offset, you might return total_count, page, and page_size. But for cursors, total_count is often expensive to compute; I skip it unless the client really needs it.

Practical Advice

Start with cursor-based pagination for any API that might grow. It's not that much harder.
Always sort by a unique column to avoid missing or duplicating items.
Use LIMIT + 1 to check if there's a next page without a separate count query.
Document your pagination clearly; clients need to know how to navigate.

I've seen too many APIs suffer from offset pagination at scale. The shift to cursors is like moving from a bicycle to a car: you don't realize how much friction you had until you switch. For new projects, I default to cursor-based. For existing ones, I gradually migrate endpoints that show performance issues.

Pagination is a small part of the API, but it affects user experience and server load every day. Choose wisely, and your future self will thank you.

Environment Config the Clean Way

Stack Horizon — Fri, 28 Aug 2026 00:00:42 +0000

Stop Hardcoding, Start Centralizing

We've all been there: const apiUrl = 'https://staging.example.com' sitting at the top of a random file. Then someone pushes it to production and the app starts talking to staging. Or worse, you have ten .env files scattered across microservices with slightly different variable names. This is a config nightmare.

The clean way is to treat environment configuration as a first-class concern: centralize it, validate it, and access it through a typed, consistent interface. Here's how I do it in Node.js, and the pattern translates to any language.

The Core Principle: One Place, One Truth

All environment variables should be loaded in a single module, transformed into a structured object, and exported. No other file should read process.env directly. This gives you a single place to add defaults, validate types, and document what's available.

Step 1: Load and Parse

First, I use dotenv to load a .env file in development (never commit it, but do commit a .env.example). Then I read variables with sensible defaults.

// config/index.js
import dotenv from 'dotenv';

dotenv.config();

const config = {
  env: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT, 10) || 3000,
  database: {
    url: process.env.DATABASE_URL,
    poolSize: parseInt(process.env.DB_POOL_SIZE, 10) || 10,
  },
  redis: {
    host: process.env.REDIS_HOST || 'localhost',
    port: parseInt(process.env.REDIS_PORT, 10) || 6379,
  },
  logLevel: process.env.LOG_LEVEL || 'info',
};

export default config;

Note the parseInt calls. Environment variables are always strings, so converting to numbers here prevents bugs later. Also, I'm grouping related settings into nested objects, which keeps the export clean.

Step 2: Validate Early, Fail Fast

Missing required variables should crash the app at startup, not halfway through a request. I use a tiny validation function or a library like envalid. Here's a manual check that's easy to read:

// config/validate.js
function required(value, name) {
  if (value === undefined || value === '') {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

const config = {
  // ...
  database: {
    url: required(process.env.DATABASE_URL, 'DATABASE_URL'),
    // ...
  },
};

If you want a more declarative approach, envalid is great. It gives you types, defaults, and validation in one shot.

Step 3: Use a Config Service in Your App

Now, instead of importing process.env everywhere, you import your config object. For example, in an Express app:

// app.js
import config from './config/index.js';
import express from 'express';

const app = express();

app.listen(config.port, () => {
  console.log(`Server running in ${config.env} on port ${config.port}`);
});

In a database client:

// db.js
import config from './config/index.js';

const pool = new Pool({ connectionString: config.database.url });

This makes your code testable too. In tests, you can override config with a mock object, no need to mess with process.env.

Step 4: Keep Secrets Out of Code

Never hardcode secrets like API keys or passwords. Use environment variables, and for production, use a secrets manager (AWS Secrets Manager, Vault, etc.) that injects them into the environment at runtime. Your config module doesn't care where they come from; it just reads them.

Step 5: Document with a `.env.example`

Commit a .env.example file so other developers know what to set. Include comments for each variable.

# .env.example
NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
DB_POOL_SIZE=10
REDIS_HOST=localhost
REDIS_PORT=6379
LOG_LEVEL=info

What About Other Languages?

The same pattern applies everywhere. In Python, use pydantic or python-dotenv. In Go, use envconfig or viper. The idea is universal: centralize, validate, and expose a typed config object.

The Payoff

No more magic strings scattered across the codebase.
Startup fails fast if required config is missing.
Easy to test by mocking the config module.
Onboarding is simpler with a clear .env.example.

It's a small investment that pays off every time you deploy to a new environment or debug a configuration issue. Your future self will thank you.

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.

DEV Community: Stack Horizon

TypeScript Features Worth Adopting First

1. strict mode in tsconfig

2. Union types and narrowing

3. unknown instead of any

4. Type guards and satisfies

5. Utility types you'll actually use

What to skip for now

The order that works

Database Indexing That Actually Speeds Things Up

The index only helps if the query can use it

Column order in a composite index matters

Covering indexes avoid the table lookup

Selectivity decides whether it is worth it

Verify with the plan, not with hope

A few habits that keep indexes honest

API Pagination Patterns: Offset, Cursor, and Keyset Explained

API Pagination Patterns: Offset, Cursor, and Keyset Explained

Offset Pagination

Cursor Pagination

Keyset Pagination

Choosing the Right Pattern

Real-World Example: Building a Simple Cursor

Final Thoughts

Debugging Node.js Like a Pro

Start with the Built-in Inspector

Use the Debugger Statement

Async Debugging with AsyncLocalStorage

Read the Stack Trace Properly

Handle Unhandled Rejections Explicitly

Use Logging Levels, Not Just console.log

Debug Memory Leaks with Heap Snapshots

Profile CPU Usage

Test With Realistic Input

The Power of --trace-warnings

Wrap Up

JWT Auth Without the Confusion

The Problem with JWT Tutorials

What JWT Actually Is

The Flow in Plain English

Minimal Node.js Implementation

Client-Side Usage (Fetch)

Common Mistakes and How to Avoid Them

1. Storing Secrets in Client Code

2. Not Checking Expiration

3. Putting Sensitive Data in the Payload

4. Using localStorage for High-Security Apps

When JWT Makes Sense

When to Avoid It

Final Thoughts

async/await without the pitfalls

async/await without the pitfalls

Pitfall 1: Forgetting await in a loop

Pitfall 2: Swallowing errors silently

Pitfall 3: Sequential execution when you need parallel

Pitfall 4: Using async when you don't need it

Pitfall 5: Ignoring cancellation

Pitfall 6: Forgetting that await blocks the event loop

Final tips

API Pagination Patterns: Choosing the Right Approach

API Pagination Patterns: Choosing the Right Approach

Offset Pagination (The Classic)

Cursor-Based Pagination (Keyset)

Keyset with Composite Cursors

Page-Based with a Token (Offset + Cursor Hybrid)

Limit/Offset with a Stable Sort

Time-Based Pagination

What About GraphQL?

Choosing What to Return

Practical Advice

Environment Config the Clean Way

Stop Hardcoding, Start Centralizing

The Core Principle: One Place, One Truth

Step 1: Load and Parse

Step 2: Validate Early, Fail Fast

Step 3: Use a Config Service in Your App

Step 4: Keep Secrets Out of Code

Step 5: Document with a .env.example

What About Other Languages?

The Payoff

1. `strict` mode in tsconfig

3. `unknown` instead of `any`

4. Type guards and `satisfies`

The Power of `--trace-warnings`

4. Using `localStorage` for High-Security Apps

Pitfall 1: Forgetting `await` in a loop

Pitfall 4: Using `async` when you don't need it

Pitfall 6: Forgetting that `await` blocks the event loop

Step 5: Document with a `.env.example`

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)