DEV Community: 날다람쥐

I tried every TypeScript Result library. So I built a better one.

날다람쥐 — Tue, 28 Apr 2026 16:22:34 +0000

I've been writing TypeScript for years, and try/catch has always bothered me.

Not because error handling is hard — but because errors are invisible in the type system. A function that says Promise<User> might throw. Or might not. You genuinely can't tell without reading the implementation.

So I went looking for a library that solves this properly.

I tried them all. None of them were quite right.

So I built verdict-ts.

The problem, quickly

// This function signature is lying to you
async function getUser(id: string): Promise<User>

// It can actually do this at runtime
// Uncaught Error: Network timeout
// Uncaught SyntaxError: Unexpected token in JSON
// Uncaught TypeError: Cannot read properties of null

The solution Rust came up with: make failure part of the return type.

// This function tells the truth
async function getUser(id: string): Promise<Result<User, ApiError>>

Now the compiler won't let you access the user without handling the error case first. Failures are visible. The type doesn't lie.

Why not the existing libraries?

Great question — and honestly the main reason I'm writing this post. Let's go through them.

neverthrow

The most popular option, and for good reason — it works well and is actively maintained. But it has one fundamental design choice I kept bumping into:

It's class-based.

import { ok, err } from 'neverthrow';

const result = ok(42);
result instanceof ResultOk; // true

Classes mean prototype chains, and prototype chains cause real problems:

// ❌ Breaks across Worker boundaries
const worker = new Worker('./worker.js');
worker.postMessage(result); // structured clone strips the prototype
// Other side receives a plain object — methods are gone

// ❌ Breaks across iframes
// ❌ JSON.stringify loses the methods
// ❌ structuredClone loses the methods

// This silently fails at runtime even though TypeScript says it's fine

If you're building for Cloudflare Workers, Next.js Edge Runtime, or anything that crosses a serialization boundary — classes are a footgun.

Also, at 112KB unpacked, it's larger than I'd want for a utility that goes into other packages as a dependency.

true-myth

Solid functional programming library. If you want Maybe<T> alongside Result<T, E>, it's excellent.

But: 793KB unpacked. That's not a typo.

It also requires you to buy into its full worldview — Maybe, Task, the whole functional ecosystem. If you just want Result, you're bringing in a lot you won't use.

ts-results

Spiritually the closest to what I wanted. But:

Last published: May 2022. Three years without an update.
TypeScript has changed a lot since then — inference has gotten smarter, and ts-results doesn't take advantage of it.
Issues have been piling up without responses.
Weaker tuple inference in combine().

result.ts

Has a dependency (maybe.ts). That immediately ruled it out — if I'm adding this as a dependency to my own packages, I don't want transitive deps creeping in.

What verdict-ts does differently

1. Plain objects, not classes

const result = ok(42);
// Literally: { ok: true, value: 42 }

JSON.stringify(result);      // ✅ works
structuredClone(result);     // ✅ works
postMessage(result);         // ✅ works across Workers

No prototype, no instanceof, no serialization surprises. It's just data.

2. Zero dependencies

{
  "dependencies": {}
}

When verdict-ts goes into your SDK as a dependency, nothing comes with it.

3. 491 bytes gzipped

For comparison: neverthrow is ~4KB gzipped, true-myth is ~12KB. verdict-ts is smaller than most SVG icons (491B — yes, really).

4. Proper tuple inference in combine()

Every Result library has combine(). Most of them return Result<T[], E>, which loses the tuple type:

// Other libraries:
combine([ok(1), ok("hello")])
// Result<(number | string)[], Error>  ← types are merged, index info lost

// verdict-ts:
combine([ok(1), ok("hello")])
// Result<[number, string], Error>  ← tuple preserved, index 0 is number, index 1 is string

This matters for validation:

const result = combine([
  validateEmail(email),    // Result<string, ValidationError>
  validateAge(age),        // Result<number, ValidationError>
  validateUsername(name),  // Result<string, ValidationError>
]);

result.match({
  ok: ([email, age, username]) => {
    //   ^^^^^ string  ^^^ number  ^^^^^^^^ string
    // TypeScript knows all three types at each index
    createUser({ email, age, username });
  },
  err: (e) => showError(e.message),
});

5. AsyncResult<T, E> type alias

A small thing that makes async code much cleaner:

import type { AsyncResult } from 'verdict-ts';

// Instead of this
async function getUser(id: string): Promise<Result<User, ApiError>>

// Write this
async function getUser(id: string): AsyncResult<User, ApiError>

The full API

import {
  ok, err,          // constructors
  trySync,          // wrap synchronous throwables
  tryAsync,         // wrap async throwables
  combine,          // merge multiple Results
  isOk, isErr,      // type guards
} from 'verdict-ts';

import type { Ok, Err, Result, AsyncResult } from 'verdict-ts';

Creating Results:

ok(42)                     // Ok<number>
err(new Error('oops'))     // Err<Error>
err({ code: 404 })         // Err<{ code: number }>

trySync(() => JSON.parse(str))                  // Result<unknown, Error>
await tryAsync(() => fetch(url))                // Result<Response, Error>

Transforming:

result
  .map(value => value * 2)               // transform Ok value
  .mapErr(e => new AppError(e.message))  // transform Err
  .flatMap(value =>                      // Ok → another Result
    value > 0 ? ok(value) : err('negative')
  )

Extracting:

result.unwrap()           // value or throws
result.unwrapOr(0)        // value or default
result.match({
  ok: v => `got ${v}`,
  err: e => `failed: ${e}`,
})

Real-world example: API client

This is the pattern that made me want to build this. When you write an SDK, your functions should tell the truth about what can fail:

import { tryAsync, ok, err } from 'verdict-ts';
import type { AsyncResult } from 'verdict-ts';

type ApiError =
  | { kind: 'network'; message: string }
  | { kind: 'not_found'; id: string }
  | { kind: 'unauthorized' }

async function getUser(id: string): AsyncResult<User, ApiError> {
  const response = await tryAsync(() => fetch(`/api/users/${id}`));

  return response
    .mapErr(e => ({ kind: 'network' as const, message: e.message }))
    .flatMap(res => {
      if (res.status === 401) return err({ kind: 'unauthorized' as const });
      if (res.status === 404) return err({ kind: 'not_found' as const, id });
      return tryAsync(() => res.json()).mapErr(e => ({
        kind: 'network' as const,
        message: e.message,
      }));
    });
}

// Caller gets full type safety on the error
const result = await getUser('123');

result.match({
  ok: (user) => renderProfile(user),
  err: (e) => {
    switch (e.kind) {
      case 'network':      return showNetworkError(e.message);
      case 'not_found':    return showNotFound(e.id);
      case 'unauthorized': return redirectToLogin();
    }
    // TypeScript ensures all cases are handled
  },
});

No try/catch. No unknown errors. Every failure mode is in the type.

Quick comparison table

	verdict-ts	neverthrow	true-myth	ts-results
Size (gzipped)	491B	~4KB	~12KB	~3KB
Dependencies	0	0	0	0
Class-based	❌	✅	✅	✅
JSON-serializable	✅	❌	❌	❌
Tuple inference	✅	❌	❌	❌
AsyncResult type	✅	✅	✅	❌
Active maintenance	✅	✅	✅	❌
Edge Runtime safe	✅	⚠️	⚠️	⚠️

Install

npm install verdict-ts

import { ok, err, tryAsync } from 'verdict-ts';

const result = await tryAsync(() =>
  fetch('https://api.github.com/users/torvalds').then(r => r.json())
);

const name = result
  .map(user => user.name)
  .unwrapOr('unknown');

console.log(name); // "Linus Torvalds"

npm: npmjs.com/package/verdict-ts

If this was useful, a ⭐ on GitHub goes a long way — it helps other developers find the project when they're searching for exactly this kind of library.

👉 github.com/flyingsquirrel0419/verdict-ts

What's your current approach to error handling in TypeScript? Still on try/catch, or have you switched to Result types? Would love to hear in the comments 👇

I got tired of AI agents trashing my codebase, so I built a skill to fix that

날다람쥐 — Mon, 27 Apr 2026 17:25:00 +0000

Every AI coding agent I've used hits the same wall. It always starts the same way.

You ask it to add a feature. It rewrites half the file in its preferred naming convention. Your snake_case Python suddenly has camelCase crammed in. The test framework you carefully chose? Gone, replaced by a different one the model apparently likes better.

So you fight it back into shape. Then you ask it to fix a bug. Same thing happens. It "tidies up" a few unrelated functions while it's in there. Opens three files you didn't ask it to touch. Leaves a commented-out console.log in production code.

Then the worst one: you hit three failures in a row on a gnarly bug, and the agent just keeps trying random things. No backoff. No ask-for-help. Just vibes and increasingly desperate code changes until the whole file is a mess.

I've context-window-pasted my way through this more times than I want to admit. Not because the agents are bad — they're genuinely powerful — but because there's no agreed-upon discipline baked in. No "read the room before you touch anything." No "when you're stuck three times in a row, stop and ask."

So I spent some time vibe coding a skill file to fix that, and turned it into 🐿️ Squirrel.

What it actually does

Squirrel is a single Markdown file (SKILL.md) that you drop into your AI agent's instruction path. It installs a full 8-phase engineering discipline into your agent, without you having to remind it every session.

[1] 🔍 Discover  → Audit the project before touching a single line
[2] 📋 Plan      → Task list with dependencies and done-criteria
[3] 💻 Build     → Write or modify code
[4] 🧪 Test      → Run existing tests, write new ones
[5] 🐛 Bug Hunt  → Static analysis + manual checklist
[6] ✨ Polish    → Lint, format, type check
[7] 📖 Document  → README + inline docs (update, don't overwrite)
[8] 🚀 Ship      → Final checklist before handoff

The key insight is Step 0 — before the agent does anything, it figures out what kind of project it's looking at:

What it sees	Mode
Empty directory	🆕 Greenfield — start from scratch
Source files, no tests	🔧 In-Progress — audit first, then improve
Source + tests + CI + README	🏗️ Mature — targeted improvements only
"fix this bug / add this feature"	🎯 Targeted — abbreviated audit, scoped work

Then it announces the mode to you. So you know it read your code before it started writing.

The "respect existing code" problem

This is the thing I cared most about getting right. Squirrel explicitly teaches the agent:

Match the existing naming convention — if the project uses snake_case, don't introduce camelCase
Use the existing test framework — don't swap in a new one because it's newer
Read 2-3 similar files before writing a new one, to understand the pattern
Touch only what's necessary — "add a password reset endpoint" is not permission to refactor the auth module

In practice this means adding something like this to the SKILL.md:

## For existing code:
- **Match the codebase's style** — check .eslintrc, pyproject.toml, rustfmt.toml
- **Read before writing** — look at 2-3 similar existing functions first
- **Touch only what's necessary**
- **Leave the codebase better than you found it**, scoped to what you touched

Sounds obvious, right? But without it being explicit in the agent's instruction context, most models default to "write it my way."

Solving the infinite debugging loop

The part I found most satisfying to design: the 3-Strike Rule.

Strike 1: Fix the specific error. Run tests. Move on.

Strike 2: Re-read the code more carefully. Try a different approach.

Strike 3: STOP. Revert. Write a failure report. Ask the user.

## After Strike 3:
1. STOP all edits
2. REVERT to last known working state (git stash)
3. Write a failure report:
   - What I tried
   - What went wrong
   - Where I think the problem is
   - What I've ruled out
4. ASK THE USER
5. NEVER: leave code broken, delete failing tests, shotgun-debug

This alone has saved me from agent death spirals more than once. Instead of watching it make 12 increasingly confused changes to the same function, it stops at 3, tells me what it knows, and asks. Like a junior engineer would.

Works on 8 platforms, install in one line

The whole thing is just Markdown. Every major AI coding agent reads Markdown instructions — the YAML frontmatter is consumed by OpenCode, silently ignored by everything else.

# Auto-detect your agent and install
curl -fsSL https://raw.githubusercontent.com/flyingsquirrel0419/squirrel-skill/main/install.sh | bash

# Or for a specific platform
bash install.sh --platform cursor
bash install.sh --platform claude-code
bash install.sh --platform aider

Supported: OpenCode, Codex, Claude Code, Cursor, Windsurf, Aider, Cline, GitHub Copilot.

If you just want minimal setup that covers four platforms at once, drop AGENTS.md in your project root. Natively read by Codex, Cursor, Cline, and Claude Code.

For Cursor specifically, add the frontmatter:

---
description: Squirrel full-cycle development skill
alwaysApply: true
---

Then paste the SKILL.md content below it.

Reference files included

Squirrel ships with supplementary templates the agent loads on demand — not all upfront, only when relevant:

File	Loaded when
`references/plan_template.md`	Phase 1, creating Plan.md
`references/readme_template.md`	Phase 7, writing a new README
`references/stack_hints.md`	Phase 3, unfamiliar languages or stacks
`references/ci_templates.md`	Phase 8, setting up GitHub Actions

The CI templates cover Node.js, Python, Go, Rust — ready-to-use starting points, not drop-in guarantees.

What vibe coding this taught me

I built Squirrel as a vibe coding exercise — give the agent a clear goal, iterate fast, let it do the heavy lifting. It was the first time I really leaned into that workflow end-to-end on something I cared about shipping.

The irony isn't lost on me: I needed better agent discipline to build a skill that teaches agents discipline. Every time the agent went sideways during development, I'd notice what rule was missing and add it to SKILL.md. The 3-Strike Rule came from a particularly painful afternoon of watching it loop on a bash parsing edge case.

By the end, the skill file had basically written itself — not because the AI wrote it, but because the failures showed me exactly what needed to be in it.

Getting started

# One liner
curl -fsSL https://raw.githubusercontent.com/flyingsquirrel0419/squirrel-skill/main/install.sh | bash

# Then tell your agent what you want:
> squirrel this project — add tests, fix lint errors, write README
> build me a REST API for a todo app with TypeScript
> fix this bug in src/auth/login.py

The agent announces which mode it detected, runs the phases, and gives you a summary at the end.

GitHub: https://github.com/flyingsquirrel0419/squirrel-skill

If this is useful to you, a ⭐ on GitHub genuinely helps — it's what tells me whether to keep building this out. Thanks for reading.

I got tired of deploying broken configs, so I built dotenv-scan

날다람쥐 — Mon, 27 Apr 2026 16:38:00 +0000

Every team I've worked on has had this incident at least once.

Friday afternoon deploy. CI is green. You push to production. Five minutes later, someone's pinging you in Slack: the app is crashing on startup. You SSH in, check the logs, and there it is:

Error: DATABASE_URL is not defined

You forgot to add the new environment variable to production. The .env file on your machine has it. The .env.example in the repo doesn't. Nobody noticed during review.

Half an hour of your Friday afternoon gone.

The fix is always the same — add the variable, redeploy, move on. But the problem keeps coming back. Because there's no automated check. You're relying on code review and memory.

And it's not just missing variables. The opposite problem is just as real: .env files that accumulate junk. OLD_REDIS_URL from a migration you finished six months ago. LEGACY_API_KEY for a service you sunset last quarter. They sit there, silently, because nobody wants to delete something they're not 100% sure is unused.

I've fixed this manually too many times. So I built dotenv-scan to do it automatically.

What it does

dotenv-scan scans your codebase for every env variable your code actually uses, then compares that against what's in your .env and .env.example. One command, three answers.

npx dotenv-scan scan

dotenv-scan v1.0.0  ·  scanned 47 files in 284ms

❌  Missing  (3)
   DATABASE_URL      src/db.ts:12, src/config.ts:8
   JWT_SECRET        src/auth/middleware.ts:4
   STRIPE_API_KEY    src/payments/stripe.ts:22

⚠️  Undocumented  (2)
   INTERNAL_API_KEY
   DEBUG_MODE

🗑️  Unused  (1)
   OLD_REDIS_URL

✅  OK  (8)
   PORT, NODE_ENV, API_BASE_URL, ... (and 5 more)

────────────────────────────────────────
Run `dotenv-scan generate` to update .env.example

No config file. No setup. Just npx and go.

The three problems it catches

Missing — your code does process.env.DATABASE_URL but .env doesn't have it. This is the Friday deploy problem. dotenv-scan catches it before you push.

Unused — .env has OLD_REDIS_URL but no file in your codebase references it. Safe to delete. dotenv-scan tells you which ones.

Undocumented — .env has INTERNAL_API_KEY but .env.example doesn't mention it. The next developer to clone your repo has no idea this variable needs to exist. dotenv-scan flags it.

Plugging it into CI

The check command is designed for pipelines. It exits with code 1 if any variables are missing:

# GitHub Actions
- name: Check env variables
  run: npx dotenv-scan check

That's the whole setup. Now your Friday deploy problem becomes a PR-time failure instead.

If you want to be strict — fail on unused and undocumented too:

dotenv-scan check --strict

Auto-generating `.env.example`

The part I actually use the most is generate. It writes (or updates) .env.example from your scan results:

dotenv-scan generate

It's idempotent. If a key already exists in .env.example, it's preserved. New variables found in the scan get added. Variables in .env.example that are no longer referenced in your code get flagged.

One command to keep your docs in sync with reality.

Multi-language support

It's not just JavaScript. The scanner understands:

Language	Patterns
JavaScript / TypeScript	`process.env.VAR`, `process.env['VAR']`
Python	`os.environ['VAR']`, `os.getenv('VAR')`, `os.environ.get('VAR')`
Go	`os.Getenv("VAR")`
Ruby	`ENV['VAR']`, `ENV.fetch('VAR')`

So if you have a monorepo with a Node.js API and a Python worker, one scan covers both.

The interesting part: detecting dynamic access

The hardest case to handle was process.env[dynamicKey].

Static analysis can't tell you which variable this reads. The key is computed at runtime — maybe it comes from a config file, maybe it's user input, maybe it's constructed from an enum. You can't enumerate it.

I made a deliberate call here: don't try to be clever. Instead, detect the pattern and warn the user:

⚠️  Dynamic access detected
   process.env[key]   src/config/loader.ts:34

   Static analysis can't determine which variables are accessed here.
   Make sure these variables are covered in your .env.example manually.

Silently ignoring it would be worse — you'd get a false "all clear" and miss variables. Failing hard would be too noisy for codebases that use this pattern intentionally. A warning with the exact location felt right.

Architecture in one diagram

CLI (Commander.js)
    │
    ├── Scanner ── Walker (fast-glob) ── Extractors (per-language regex)
    │                                              │
    │                                     EnvRef[] (used variables)
    │
    ├── Parser ── dotenv parser ── EnvDef[] (defined variables)
    │
    └── Analyzer ── compares used ↔ defined ↔ documented
                         │
                    AnalysisResult
                         │
                    ┌────┴────┐
                 Reporter   Generator
                (text/json)  (.env.example)

Each layer is independently testable. The scanner doesn't know about .env files. The analyzer doesn't know about file systems. 88 tests, zero mocks of the actual fs calls in integration tests — they run against real fixture files.

Zero runtime dependencies (almost)

Three runtime deps, all small:

chalk — terminal colors
commander — CLI argument parsing
fast-glob — file walking

That's it. No dotenv library — the parser is custom because I needed comment-preservation and multiline value support that dotenv packages tend to strip. No framework. Ships as a standalone CLI that you can npx without worrying about what it pulls in.

Getting started

# No install required
npx dotenv-scan scan

# Or install globally
npm install -g dotenv-scan

GitHub: https://github.com/flyingsquirrel0419/dotenv-scan

If dotenv-scan saves you from a bad deploy, a ⭐ on the repo goes a long way. It's also the best way to let me know it's useful so I keep working on it.

The thing I keep coming back to is how small the fix is relative to how painful the problem is. One npx command in CI, and the whole class of "missing env variable in production" goes away. I wish I'd built this years ago.

Happy to dig into any of the implementation details in the comments — the multi-language extractor design and the dynamic access detection decision both have interesting tradeoffs worth talking through.

I Audited My Own Open Source Library and Found 9 Security Bugs. Here's Every One.

날다람쥐 — Sun, 26 Apr 2026 01:14:50 +0000

Hey dev.to 👋

If you've read my previous post about layercache, you know it's a multi-layer caching library for Node.js — Memory → Redis → Disk behind a single get() call, with stampede prevention, tag invalidation, circuit breaking, and all the production-grade stuff you eventually need.

Today I'm releasing v1.3.3, and it's different from all the previous releases.

No new features. No benchmark numbers. No shiny API additions.

Just nine bugs I found in my own library. I want to walk through all of them — what they were, why they happened, and what I did to fix them.

Some are embarrassing. All of them are real.

Why I did a full security audit

When you're building in the open and people start actually using the thing, you feel differently about the code. I went back through the internals with fresh eyes and a specific question: what could go wrong in production under real load?

Turns out: a lot.

Here's everything I found, roughly in severity order.

VULN-1 (HIGH): Unbounded memory growth in `keyEpochs`

The bug: CacheStackMaintenance uses a Map<string, number> called keyEpochs to track write invalidation — every time a key is deleted or updated, its epoch is bumped so stale write-behind operations know to skip it. The map grew forever. No cap, no pruning. In a long-running service writing lots of unique keys, this is a slow memory leak that only gets worse over time.

The fix: Added MAX_KEY_EPOCHS = 50_000 and a pruning step after every bumpKeyEpochs() call. When the map exceeds the limit, the oldest 10% (lowest epoch values) get evicted.

+ const MAX_KEY_EPOCHS = 50_000

  bumpKeyEpochs(keys: string[]): void {
    for (const key of keys) {
      this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1)
    }
+   this.pruneKeyEpochsIfNeeded()
  }

+ private pruneKeyEpochsIfNeeded(): void {
+   if (this.keyEpochs.size <= MAX_KEY_EPOCHS) return
+   const sorted = [...this.keyEpochs.entries()].sort((a, b) => a[1] - b[1])
+   const toDelete = Math.ceil(sorted.length * 0.1)
+   for (let i = 0; i < toDelete; i++) {
+     this.keyEpochs.delete(sorted[i][0])
+   }
+ }

This one stings because it's exactly the kind of bug that's invisible in tests — you only see it after the process has been running for days and memory graphs start climbing.

VULN-2 (MED-HIGH): Unbounded queue in `FetchRateLimiter`

The bug: FetchRateLimiter queues fetcher requests per-bucket when rate limits are hit. The queue itself had no bound. Under sustained high contention on a single cache key, that queue would grow without limit — eventually consuming unbounded memory and causing backpressure to pile up indefinitely.

The fix: Added MAX_QUEUE_PER_BUCKET = 10_000. When a bucket's queue is full, new requests bypass the rate limiter entirely rather than blocking (availability > strict throttling in this failure mode).

+ const MAX_QUEUE_PER_BUCKET = 10_000

  return new Promise<T>((resolve, reject) => {
    const bucketKey = this.resolveBucketKey(normalized, context)
    const queue = this.queuesByBucket.get(bucketKey) ?? []
+   if (queue.length >= MAX_QUEUE_PER_BUCKET) {
+     this.rateLimitBypasses += 1
+     task().then(resolve, reject)
+     return
+   }
    queue.push({ bucketKey, options: normalized, task, resolve, reject })
    ...
  })

The bypass counter is exposed via metrics so you can see when it's happening in production.

VULN-3 (MEDIUM): CLI accepted unvalidated input before hitting Redis

The bug: The admin CLI (npx layercache keys --pattern "...", invalidate --tag "...", etc.) didn't validate keys, patterns, or tags before passing them to Redis operations. The runtime CacheStack enforces strict validation on all inputs — the CLI was just... not doing that.

The fix: The same validateCacheKey(), validatePattern(), and validateTag() functions used by the runtime are now called in the CLI before any Redis operation runs.

// cli.ts — now applied before every Redis op
if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return
if (args.tag && !validateCliInput(args.tag, validateTag)) return
if (args.key && !validateCliInput(args.key, validateCacheKey)) return

The runtime had this hardened back in v1.2.x. The CLI just... never got the memo.

VULN-4 (MEDIUM): `invalidate` could wipe the entire cache with no confirmation

The bug: Running npx layercache invalidate with no --pattern or --tag defaults to * — which matches every key in the cache. There was no confirmation step. One mistyped command in a terminal and your entire production cache is gone.

The fix: If you run invalidate with no targeting flags and there are keys to delete, the CLI now refuses and asks you to pass --force explicitly.

$ npx layercache invalidate
Warning: this operation will invalidate 14,823 keys. Use --force to confirm.

$ npx layercache invalidate --force
Invalidated 14,823 keys.

This one is embarrassing because I added the CLI for convenience in production, and then left a footgun that could nuke the entire cache by accident. Glad I caught it before anyone else did.

VULN-5 (MEDIUM): `TagIndex` pruning was silently broken

The bug: TagIndex uses a knownKeys collection to track which keys exist, so prefix and wildcard invalidation can find them. Since v1.2.0, it had a maxKnownKeys limit to prevent unbounded growth — but it was a Set<string>, which has no access-recency ordering. The pruning code sorted and evicted by... nothing meaningful. It was effectively random deletion, not LRU eviction. Hot keys were just as likely to get pruned as cold ones.

The fix: Changed knownKeys from Set<string> to Map<string, number> where the value is a timestamp updated on every touch() or track() call. Now pruning correctly evicts least-recently-used entries.

- private readonly knownKeys = new Set<string>()
+ private readonly knownKeys = new Map<string, number>()  // key → last-touched timestamp

  async touch(key: string): Promise<void> {
-   this.knownKeys.add(key)
+   this.knownKeys.set(key, Date.now())  // updates on every access
    this.pruneKnownKeysIfNeeded()
  }

  private pruneKnownKeysIfNeeded(): void {
    if (!this.maxKnownKeys || this.knownKeys.size <= this.maxKnownKeys) return
-   // old: iterated a Set with no ordering guarantee
+   const sorted = [...this.knownKeys.entries()].sort((a, b) => a[1] - b[1])
+   const toDelete = Math.ceil(sorted.length * 0.1)
+   for (let i = 0; i < toDelete; i++) this.knownKeys.delete(sorted[i][0])
  }

The limit was there since v1.2.0 and looked like it was working. It wasn't.

VULN-6 (MEDIUM): TOCTOU race in snapshot file writes

The bug: The snapshot persistence code (persistToFile()) wrote directly to the target path. If the process crashed mid-write, you'd get a partial or corrupt snapshot file with no recovery path. Worse, if two processes tried to write a snapshot concurrently, they'd clobber each other.

The fix: Centralized all snapshot writes through two new utilities: atomicWriteTempPath() generates a randomized temp filename, and commitAtomicWrite() renames the temp file to the target — an atomic operation on all POSIX-compliant filesystems.

// src/internal/CacheSnapshotFile.ts

export function atomicWriteTempPath(targetPath: string): string {
  return `${targetPath}.tmp-${randomBytes(8).toString('hex')}`
}

export async function commitAtomicWrite(tempPath: string, targetPath: string): Promise<void> {
  try {
    await rename(tempPath, targetPath)
  } catch (error) {
    await unlink(tempPath).catch(() => undefined)
    throw error
  }
}

Write to the temp path, then fs.rename(). If anything goes wrong before the rename, the original snapshot is untouched. If the rename succeeds, readers see either the old file or the new one — never a partial state.

VULN-7 (LOW): Memory leak in `layerDegradedUntil`

The bug: When a cache layer fails and enters degraded mode, CacheStack stores layerDegradedUntil.set(layer.name, expiryTimestamp). When the degradation period expired, the entry was never removed. In a service where Redis occasionally has brief hiccups, this map accumulates an entry per layer per incident — forever.

The fix: On every read that checks degradation status, if the entry has expired, delete it before returning.

  const degradedUntil = this.layerDegradedUntil.get(layer.name)
  const skip = shouldSkipDegradedLayer(degradedUntil)
+ if (!skip && degradedUntil !== undefined) {
+   this.layerDegradedUntil.delete(layer.name)  // clean up expired entry
+ }

One-liner fix, but this would quietly accumulate in any service that ever experiences Redis downtime.

VULN-8 (LOW): `Math.random()` for TTL jitter

The bug: TtlResolver.applyJitter() used Math.random() to spread cache expiration times. Math.random() is not cryptographically secure — it's seeded from a deterministic internal state. For TTL jitter this is mostly harmless, but using a predictable PRNG to compute expiration windows is bad practice. In theory, an observer who can measure cache miss patterns could infer when keys are about to expire.

The fix: Replaced Math.random() with a crypto.randomBytes-based equivalent.

+ import { randomBytes } from 'node:crypto'

+ export const secureRandom = {
+   value(): number {
+     return randomBytes(4).readUInt32BE(0) / 0x100000000
+   }
+ }

  applyJitter(ttl: number | undefined, jitter: number | undefined): number | undefined {
    if (!ttl || ttl <= 0 || !jitter || jitter <= 0) return ttl
-   const delta = (Math.random() * 2 - 1) * jitter
+   const delta = (secureRandom.value() * 2 - 1) * jitter
    return Math.max(1, Math.round(ttl + delta))
  }

randomBytes(4) is fast. No measurable performance impact.

VULN-9 (LOW): Background refresh failures logged at `debug` level

The bug: When a stale-while-revalidate background refresh fails — upstream is down, fetcher throws, timeout — the error was logged at debug level. In almost every production setup, debug logs are disabled. So these failures were silently swallowed. You'd see keys serving stale values with no log entry explaining why.

The fix: One-line change.

- this.logger.debug?.('background-refresh-failed', { key, error })
+ this.logger.warn?.('background-refresh-failed', { key, error })

I genuinely don't know how long this was invisible. If you've been running layercache with staleWhileRevalidate and wondering why some keys feel permanently stale — this might be why.

What I learned from this

A few patterns that caused most of these bugs:

Unbounded Maps are silent killers. VULN-1, VULN-5, and VULN-7 are all variations of the same mistake: I allocated a Map or Set, put the bounds/pruning logic on my TODO list, and shipped without it. In tests, these are invisible. In production they show up in memory graphs after days of uptime.

Internal tools don't inherit production hardening automatically. VULN-3 and VULN-4 happened because the CLI was an afterthought. The core library had strict input validation. The CLI that wraps it did not. Every interface — HTTP endpoints, CLIs, admin tools — needs its own hardening pass.

"Debug-level logging" is often "no logging" in production. VULN-9 was a legitimate design decision that turned out to be wrong in practice. Background refresh failures are operational signals, not debugging details.

TOCTOU bugs hide behind success. VULN-6 was only a problem during crashes or concurrent writes — situations that don't happen in unit tests. The atomic write pattern is just the right default, regardless.

Upgrade

v1.3.3 is a drop-in upgrade. No API changes, no migration needed.

npm install layercache@latest

Full changelog: CHANGELOG.md
Security PR: #19

If you're already using layercache — please upgrade. If you're not, this might be a decent time to take a look:

🐙 GitHub: github.com/flyingsquirrel0419/layercache
📦 npm: npmjs.com/package/layercache
📖 Docs: API Reference · Tutorial

If this has been useful, a ⭐ on GitHub helps a lot — it's the main signal that helps other developers find the library. Thanks for reading. 🙏

I got tired of wiring the same caching stack every project, so I built LayerCache

날다람쥐 — Sat, 18 Apr 2026 16:40:12 +0000

Every Node.js service I've worked on hits the same caching wall. It always starts the same way.

You add an in-memory cache. It's fast. Life is good.

Then you scale to multiple instances. Now each server has its own view of the data. Stale reads start showing up in production. So you add Redis. Now all your instances share the same cache. Problem solved — until you realize every single request is paying a Redis round-trip, even for data that barely changes.

So you bring back the in-memory layer on top of Redis. Now you have L1 (memory) and L2 (Redis). But what happens when a key expires and 200 requests hit at the same time? They all miss L1, all miss L2, and they all go straight to the database simultaneously. Cache stampede. Your DB is not happy.

You add stampede protection. Then Redis goes down one day, and your entire cache blows up instead of gracefully falling back. You add circuit breaking. Then you realize your memory caches across instances are now serving different data and you need a pub/sub invalidation bus to keep them in sync...

It never ends.

I've wired this stack more than once. It's not that any single piece is hard — it's that getting all of it working together correctly, with proper testing and production-grade reliability, takes real engineering time every time.

So I built LayerCache to do it once and stop repeating myself.

What it does

LayerCache stacks multiple cache layers (Memory → Redis → Disk) behind a single get() call.

import { CacheStack, MemoryLayer, RedisLayer } from 'layercache'
import Redis from 'ioredis'

const cache = new CacheStack([
  new MemoryLayer({ ttl: 60, maxSize: 1_000 }),
  new RedisLayer({ client: new Redis(), ttl: 3600 }),
])

const user = await cache.get('user:123', () => db.findUser(123))

On a cache hit: serves the fastest available layer, then automatically backfills the layers above it. So if L1 is cold but L2 (Redis) has the value, L1 gets filled for the next request.

On a cache miss: the fetcher function runs exactly once, no matter how many requests are waiting. All concurrent callers get the same promise.

your request flood
       │
┌──────▼──────┐
│ L1 Memory   │  ~0.005 ms  ← serves from here if warm
│             │
│ L2 Redis    │  ~0.2 ms   ← falls through to here if L1 cold
│             │
│ L3 Disk     │  ~2 ms     ← optional persistent layer
│             │
│ Fetcher()   │             ← runs ONCE even under 100 concurrent requests
└─────────────┘

Solving the stampede problem

In a benchmark with 75 concurrent requests hitting an expired key:

	Origin fetches
No cache	375
LayerCache	5 (one per layer)

The local single-flight is handled by sharing an in-flight promise across concurrent callers. No mutex queue. No serialization.

For distributed environments — multiple Node.js processes or machines — RedisSingleFlightCoordinator extends this across instances using distributed locks.

import { RedisSingleFlightCoordinator } from 'layercache'

const cache = new CacheStack(layers, {
  singleFlightCoordinator: new RedisSingleFlightCoordinator({ client: redis }),
})

In a test with 60 concurrent requests across multiple instances: 1 origin fetch total.

Keeping L1 caches in sync across instances

The classic problem with in-process memory caches in a multi-instance setup: if you invalidate a key on Server A, Servers B and C still serve the old value from their L1.

LayerCache solves this with a Redis pub/sub invalidation bus.

import { RedisInvalidationBus } from 'layercache'

const cache = new CacheStack(layers, {
  invalidationBus: new RedisInvalidationBus({
    publisher: redis,
    subscriber: new Redis(), // separate connection for sub
  }),
})

// invalidating on one instance flushes L1 on all instances
await cache.delete('user:123')

When Redis dies

This is where a lot of hand-rolled caching setups break badly. LayerCache has two modes:

Strict mode (default): if any layer fails, the operation fails. Good when you need strong consistency guarantees.

Graceful degradation: failed layers are temporarily skipped. The cache keeps working by going directly to the fetcher.

const cache = new CacheStack(layers, {
  gracefulDegradation: { retryAfterMs: 10_000 },
})

I tested this with 500ms of injected Redis latency (way above the 200ms command timeout):

Scenario	Strict	Graceful
L1 warm hit	✅ 0.065 ms	✅ 0.065 ms
L2 hit (Redis slow)	❌ timeout	✅ 201 ms (fell back to fetcher)
Cold miss (Redis slow)	❌ timeout	✅ 200 ms (fell back to fetcher)

L1 hot hits aren't affected at all since they never touch Redis.

Benchmark numbers

Ran on a single-core VM with real Docker-backed Redis.

Warm hit latency

layered (L1 hit):   0.005 ms avg  (1006x faster than no-cache)
memory only:        0.010 ms avg  ( 503x faster than no-cache)
no-cache:           5.030 ms avg

HTTP throughput (autocannon, 40 connections, 8 seconds)

/layered:   16,211 req/s  —  1.9 ms avg latency
/memory:    16,031 req/s  —  1.9 ms avg latency
/nocache:      158 req/s  — 253.2 ms avg latency

Memory pressure

With L1 capped at 25 keys and 180 unique keys inserted (256 KiB each), revisits served 0 origin refetches — the layer evicted correctly and Redis backed the misses.

Full benchmark methodology and raw output: docs/benchmarking.md

Other things it does

I don't want to just dump a feature list, but a few things worth calling out:

Tag invalidation — attach tags to keys and invalidate all of them at once:

await cache.set('post:42', post, { tags: ['posts', 'user:7'] })
await cache.invalidateByTag('user:7') // clears all keys tagged with user:7

Stale-while-revalidate — return the cached value immediately, refresh in the background:

new MemoryLayer({ ttl: 60, staleWhileRevalidate: 300 })

Framework middleware — drop-in for Express, Fastify, Hono, tRPC, GraphQL:

app.get('/api/users',
  createExpressCacheMiddleware(cache, {
    ttl: 30,
    tags: ['users'],
    keyResolver: (req) => `users:${req.url}`,
  }),
  async (req, res) => res.json(await db.getUsers())
)

Admin CLI — inspect a live Redis-backed cache without writing code:

npx layercache stats
npx layercache keys --pattern "user:*"
npx layercache invalidate --tag posts

Getting started

npm install layercache

Memory-only (no Redis needed):

const cache = new CacheStack([
  new MemoryLayer({ ttl: 60 })
])

const data = await cache.get('key', () => fetchData())

Full distributed setup:

import {
  CacheStack,
  MemoryLayer,
  RedisLayer,
  RedisInvalidationBus,
  RedisSingleFlightCoordinator,
} from 'layercache'

const redis = new Redis()

const cache = new CacheStack(
  [
    new MemoryLayer({ ttl: 60, maxSize: 10_000 }),
    new RedisLayer({ client: redis, ttl: 3600, compression: 'gzip' }),
  ],
  {
    invalidationBus: new RedisInvalidationBus({
      publisher: redis,
      subscriber: new Redis(),
    }),
    singleFlightCoordinator: new RedisSingleFlightCoordinator({ client: redis }),
    gracefulDegradation: { retryAfterMs: 10_000 },
  }
)

GitHub: https://github.com/flyingsquirrel0419/layercache Please star the GitHub repo. It help me much! :>
npm: https://www.npmjs.com/package/layercache
Docs: https://github.com/flyingsquirrel0419/layercache/tree/main/docs

The part I found most interesting to design was the stampede guard — specifically making sure concurrent callers share a promise rather than queueing through a mutex, and then extending that behavior across processes with Redis. Happy to dig into any of that if you're curious.

useless-gps

날다람쥐 — Fri, 10 Apr 2026 17:50:44 +0000

This is a submission for the DEV April Fools Challenge

What I Built

I made a useless-gps website.

Demo

useless-gps.vercel.app

Code

flyingsquirrel0419 / useless-gps

useless-gps

The world's most accurate and completely useless GPS locator.

This project is a small Next.js app that reads your browser geolocation and turns it into intentionally unhelpful cosmic, geophysical, and existential status cards.

Stack

Next.js 14
React 18
TypeScript
Tailwind CSS
Framer Motion

Local Development

Install dependencies:

npm ci

Start the development server:

npm run dev

Build for production:

npm run build

Start the production server:

npm run start

How It Works

Requests browser geolocation with high accuracy enabled
Shows a fake "scan" sequence while location data is loading
Converts coordinates into humorous location cards
Renders a stylized retro radar interface with animated effects

Contribution Policy

main is a protected branch.

Do not push directly to main
Open a pull request for every change
Outside contributors should work from a fork and open a PR
Non-admin changes require operator approval before landing on main

Operator Review

Repository ownership and…

View on GitHub

How I Built It

I am interesting in space.So i want to know location of earth in space. So i made it.

Prize Category

Community Favorite : Because i build this with own coding skills. so I should choose "Community Favorite".

layercache: Stop Paying Redis Latency on Every Hot Read

날다람쥐 — Thu, 09 Apr 2026 23:53:34 +0000

Every Node.js backend hits the same wall eventually.

Your Redis cache is working, latency is acceptable, and then traffic doubles. Suddenly the Redis round-trip that felt like nothing at 200 req/s starts dominating your p95 at 2,000 req/s. You add an in-process memory cache on top, wire up some invalidation logic by hand, and three months later you are maintaining a fragile two-layer system with no stampede protection and no cross-instance consistency.

layercache is a TypeScript-first library that solves this problem once, cleanly. It stacks memory, Redis, and disk behind a single unified API and handles the hard parts — stampede prevention, cross-instance invalidation, graceful degradation under Redis failures — out of the box.

This post walks through what it does and what the benchmark numbers actually look like on a real Redis backend.

The Core Idea

your app ──▶ L1 Memory   ~0.006 ms  (per-process, sub-millisecond)
                │
             L2 Redis    ~0.2 ms    (shared across instances)
                │
             L3 Disk     ~2 ms      (optional, persistent)
                │
             Fetcher     runs once  (even under high concurrency)

On a cache hit the fastest available layer responds and the result backfills any warmer layers automatically. On a miss the fetcher runs exactly once, no matter how many concurrent requests arrived at the same time.

That last part — the single-flight guarantee — is where most hand-rolled hybrid caches fall apart.

Getting Started

npm install layercache

Memory only (no Redis needed):

import { CacheStack, MemoryLayer } from 'layercache'

const cache = new CacheStack([
  new MemoryLayer({ ttl: 60, maxSize: 1_000 })
])

const user = await cache.get('user:123', () => db.findUser(123))

Memory + Redis layered setup:

import { CacheStack, MemoryLayer, RedisLayer } from 'layercache'
import Redis from 'ioredis'

const cache = new CacheStack([
  new MemoryLayer({ ttl: 60, maxSize: 2_000 }),
  new RedisLayer({ client: new Redis(), ttl: 300, prefix: 'myapp:' })
])

const user = await cache.get('user:123', () => db.findUser(123))

The API is the same regardless of how many layers you add. Your application code doesn't change when you add or remove a layer.

Benchmark Results

I ran layercache v1.2.9 against a real Redis 7 backend (Docker, not a mock) on Linux. Here is what the numbers look like.

Warm Hit Latency

The most important number for a cache library is how fast the hit path is.

Mode	Avg ms	P95 ms
No cache (origin)	5.175	8.742
Memory only	0.009	0.014
Memory + Redis	0.005	0.006

Memory-only warm hits averaged 0.009ms. With a Redis layer added, the hot path still resolves from L1 memory and came in at 0.005ms — both are firmly sub-millisecond and effectively the same class of latency for production purposes.

Stampede Prevention

This is where the library earns its keep. 75 concurrent requests for the same missing key, repeated 5 times:

Mode	Avg ms	Origin Executions
No cache	409.5	375
Memory only	6.9	5
Memory + Redis	36.7	5

Without a cache, 75 × 5 = 375 origin calls. With layercache, the fetcher ran exactly 5 times — once per round, regardless of concurrency. The layered case is slower than memory-only because it pays Redis coordination costs, but the correctness guarantee is the same.

HTTP Throughput

Under sustained load with autocannon (40 connections, 8 seconds):

Route	Avg Latency	P97.5	Req/s
No cache	249 ms	271 ms	161
Memory only	1.82 ms	4 ms	16,705
Memory + Redis	1.74 ms	4 ms	17,184

Caching moved the service from 161 req/s to over 17,000 req/s — roughly a 100× improvement in throughput. Average latency dropped from 249ms to under 2ms. The memory-only and layered routes performed nearly identically in steady state because hot requests stay in L1 after warm-up.

What Happens When Redis Is Slow or Dead?

This is the question that separates a library you can actually run in production from one you can only trust in demos.

Slow Redis

I measured three scenarios with injected TCP latency:

Redis Delay	L1 hot hit	L2 hit	Cold miss
0ms	0.407ms	2.655ms	12.259ms
100ms	0.119ms	101.172ms	504.167ms
500ms	0.196ms	501.404ms	2506.013ms

The key insight: L1 hot hits stayed fast regardless of Redis latency. If a request can be served from in-process memory, slow Redis does not matter at all. The latency penalty only applies when a request needs to reach L2 or perform a cold miss.

Cold misses scaled hard with injected delay because the request paid both the Redis round-trip and the write-back path. If you have traffic patterns with many cold misses, a slow Redis will drag your tail latency even with gracefulDegradation enabled — the benchmark showed graceful and strict modes performing nearly identically under slow conditions.

Dead Redis

Under a fully paused Redis instance:

Warm L1 hits: still worked — both strict and graceful modes served from memory normally
Cold misses: timed out at 2000ms — both modes failed

This is important to understand. gracefulDegradation keeps warm traffic alive when Redis goes down. It does not create a fast fallback path for cold keys. New keys and expired keys that need a Redis write-back will stall until the timeout.

Operationally this means: if your L1 TTL is shorter than your expected Redis outage window, you will see degraded cold-miss behavior. Size your L1 TTLs with this in mind.

Queue Amplification Under Slow Redis

A follow-up benchmark asked: if Redis is slow and 500 concurrent requests pile up on L2-hit traffic, does latency stay bounded or blow up?

Redis Delay	Concurrency 1	Concurrency 500	Amplification
100ms	100.8ms	128.9ms	1.28×
500ms	501.1ms	515.8ms	1.03×

No runaway queue amplification. At 500 concurrent requests against a 500ms-latency Redis, wall-clock time only grew by about 15ms above the single-request baseline. The library appears to batch or overlap L2 requests within a shared Redis client rather than serializing them, which keeps the curve nearly flat.

Memory Pressure and Eviction

With maxSize: 25 and 180 unique keys inserted (each with a 256KB payload), then revisiting the earliest 25 keys:

Evictions	L1 Retained	Revisit Avg	Origin Fetches
180	25	1.332ms	0

Eviction was predictable. L1 held exactly maxSize entries after the fill phase. When evicted keys were revisited, they reloaded from Redis L2 rather than hitting the origin — zero origin fetches despite L1 having evicted everything. GC activity was measurable (36 events, 78ms total) but no stop-the-world pauses appeared at this payload size.

Multi-Instance and Cross-Process Features

Single-process benchmarks only tell part of the story. layercache ships with primitives for distributed deployments:

import {
  CacheStack, MemoryLayer, RedisLayer,
  RedisInvalidationBus,
  RedisSingleFlightCoordinator
} from 'layercache'

const redis = new Redis()

const cache = new CacheStack(
  [
    new MemoryLayer({ ttl: 60, maxSize: 10_000 }),
    new RedisLayer({ client: redis, ttl: 3600 })
  ],
  {
    invalidationBus: new RedisInvalidationBus({
      publisher: redis,
      subscriber: new Redis() // separate connection for pub/sub
    }),
    singleFlightCoordinator: new RedisSingleFlightCoordinator({ client: redis }),
    gracefulDegradation: { retryAfterMs: 10_000 }
  }
)

The edge benchmark verified both of these features work:

Cross-instance invalidation: Instance B observed the updated value after Instance A invalidated and repopulated the key.
Distributed single-flight: 60 concurrent requests split across two instances triggered exactly 1 origin fetch total.

TTL expiry stampedes are also deduplicated. In the benchmark, 40 concurrent requests hitting the same expired key across 5 rounds produced only 5 origin executions — one per expiry round.

Framework Integrations

layercache ships middleware and adapters for the major Node.js frameworks:

Express:

app.get('/api/users', createExpressCacheMiddleware(cache, {
  ttl: 30,
  tags: ['users'],
  keyResolver: (req) => `users:${req.url}`
}), handler)

NestJS:

@Module({
  imports: [CacheStackModule.forRoot({
    layers: [
      new MemoryLayer({ ttl: 20 }),
      new RedisLayer({ client: redis, ttl: 300 })
    ]
  })]
})
export class AppModule {}

Fastify, Hono, tRPC, GraphQL resolver wrappers, and Next.js App Router are also covered.

Payload Size Matters for Redis Reads

One benchmark result worth highlighting explicitly: payload size has almost no effect on L1 memory hits, but has a large effect when Redis is on the read path.

Mode	1KB avg	1MB avg
Memory hit	0.012ms	0.018ms
Redis hit	0.200ms	4.170ms

If you are storing large objects — full page renders, heavy API responses — and relying on Redis as the primary read path without a warm L1 in front, you will feel the serialization and network overhead. Keep large objects in L1 where possible, or enable compression at the Redis layer.

When to Use layercache

Good fit:

Services handling repeated reads for the same keys under any meaningful concurrency
Multi-instance deployments that need consistent cache state across processes
Situations where Redis slowdowns or outages should degrade gracefully rather than cascade
Teams that want observable caching with hits/misses/latency metrics without building the instrumentation themselves

Less relevant:

Pure write-heavy workloads with no repeated reads
Environments where an in-process memory cache is prohibited for compliance reasons
Very simple single-key caches where a plain Map with a TTL is already sufficient

Summary

Scenario	Key number
Warm L1 hit latency	~0.006ms
HTTP throughput gain (no cache → cached)	~100×
Stampede dedup (75 concurrent, 5 rounds)	375 fetches → 5
Distributed single-flight (60 requests, 2 instances)	60 fetches → 1
Slow Redis impact on hot L1 traffic	None
Dead Redis impact on warm L1 traffic	None
Dead Redis impact on cold-miss traffic	Timeout

The library makes a clear promise: stack your layers, wire up your fetcher, and it handles the coordination. The benchmarks back that promise up on a real backend.

Links:

Beyond Basic Caching: How layercache Eliminates Cache Stampedes in Node.js

날다람쥐 — Thu, 09 Apr 2026 18:21:03 +0000

Every Node.js developer knows the caching drill. You start with an in-memory Map, graduate to Redis when you scale horizontally, and eventually find yourself wiring up a fragile hybrid system that breaks in production at 2 AM.

I recently discovered layercache—a multi-layer caching toolkit that promises to handle the messy parts (stampede prevention, graceful degradation, distributed consistency) while keeping the API simple. But does it deliver?

I ran four comprehensive benchmark suites against real Redis instances to find out. Here are the results.

The Architecture: L1 + L2 + Coordination

layercache treats caching as a stack:

┌─────────────────────────────────────┐
│  L1 Memory  (~0.01ms, per-process)  │
│  L2 Redis   (~0.5ms, shared)        │
│  L3 Disk    (~2ms, persistent)      │
└─────────────────────────────────────┘

When you request a key, it checks L1 first, then L2, then your database. The clever part? All layers backfill automatically—if you hit L2, layercache populates L1 for the next request. If you hit the database, it writes to both layers.

But the real magic happens when 100 requests arrive simultaneously for the same expired key.

Benchmark 1: The Stampede Test

The "thundering herd" problem is where most caching libraries fail. When a popular key expires, 100 concurrent requests can trigger 100 database queries before the first one repopulates the cache.

I tested 75 concurrent requests across 5 runs (375 total requests) for a cold key:

Setup	Origin Fetches
No cache	375
Memory-only	5
Memory + Redis	5

Result: layercache's single-flight coordination ensured the fetcher ran exactly once per expiry round, not 75 times. The library creates a coordination lock in Redis (or memory) so that concurrent requests wait for the first fetcher to complete rather than hammering your database.

Latency under this stampede:

Mode	Avg Latency	P95
No cache	409ms	429ms
Memory-only	6.9ms	13.5ms
Layered	36.7ms	43.6ms

The layered case is slower than memory-only (it pays Redis coordination costs), but it preserves the critical property: your database only feels one request.

Benchmark 2: Real HTTP Throughput

Theory is nice, but what about real HTTP servers? I set up three Express routes—no cache, memory-only, and layered—and hit them with autocannon (40 connections, 8 seconds):

Route	Avg Latency	P97.5	Req/sec	Throughput
`/nocache`	249ms	271ms	161	57 KB/s
`/memory`	1.82ms	4ms	16,705	5.9 MB/s
`/layered`	1.74ms	4ms	17,184	6.1 MB/s

That's a 100x throughput increase with minimal latency difference between memory-only and Redis-backed layers. Once warmed, L1 memory serves the hot path while Redis provides the shared backing store for multi-instance deployments.

Benchmark 3: When Redis Goes Wrong

Production caches fail. I tested two failure modes:

Slow Redis (500ms latency injection)

Using a TCP proxy to add synthetic latency:

Scenario	Single Request	500 Concurrent	Amplification
L2 hit (strict)	501ms	515ms	1.03x
L2 hit (graceful)	501ms	512ms	1.02x

Key finding: Under slow Redis, wall-clock time stayed close to the single-request baseline even at 500 concurrent requests. The linearity ratio collapsed to ~0.002, meaning the batch completed far faster than a naive "latency × N" model would predict.

However, cold misses were brutal: With 500ms Redis latency, a cache miss took ~2.5s because it paid the slow Redis cost plus the fetch/write cost.

Dead Redis (complete outage)

I paused the Redis container with Docker:

Scenario	Success	Latency
Strict hot hit	✅	0.17ms
Graceful hot hit	✅	0.07ms
Strict cold miss	❌	Timeout (2000ms)
Graceful cold miss	❌	Timeout (2000ms)

Critical insight: gracefulDegradation did not turn a cold miss into a fast memory-only fallback when Redis was completely frozen. Hot L1 keys survived the outage beautifully (served from memory), but new or expired keys stalled until timeout.

Operational takeaway: Warm your critical keys before Redis has issues. Hot L1 traffic is your lifeline during Redis outages.

Benchmark 4: Memory Pressure and Eviction

What happens when L1 memory fills up? I set maxSize: 25 and inserted 180 unique 256KB payloads:

Metric	Value
Evictions	180
L1 Retained	25 (exactly maxSize)
Origin Fetches on Revisit	0
GC Pauses (max)	6.1ms

When revisiting the oldest keys (which were evicted from L1), they were seamlessly reloaded from Redis L2—not the origin. No cache stampede, no origin amplification.

The GC impact was measurable (36 events, 78ms total) but not catastrophic—max pause stayed at 6ms, far from stop-the-world territory.

Edge Cases: TTL Expiry and Distributed Systems

TTL Stampede Protection

I tested 40 concurrent requests hitting a key that just expired (TTL: 1s, waited 1.1s):

Mode	Fetch Count
Memory-only	5 (one per expiry round)
Layered	5 (one per expiry round)

Even with TTL expiry triggering simultaneously across multiple rounds, deduplication held firm.

Multi-Instance Consistency

Running two Node.js instances with shared Redis:

Invalidation Bus: When Instance A updated a key, Instance B's L1 cache was invalidated via Redis Pub/Sub within milliseconds.
Distributed Single-Flight: 60 concurrent requests across both instances for the same missing key resulted in exactly 1 origin fetch.

This is the holy grail for microservices: you get per-process L1 speed with cluster-wide consistency.

Payload Size Sensitivity

Does caching large objects hurt?

Setup	1KB Avg	1MB Avg	P95 (1MB)
Memory-only	0.012ms	0.018ms	0.023ms
Redis-only	0.200ms	4.170ms	10.11ms

Large payloads hurt only when Redis is on the hot path. Memory hits barely changed between 1KB and 1MB, but Redis hits jumped 20x due to serialization and network transfer. Keep your L1 maxSize generous for large objects.

Practical Takeaways

After running these benchmarks, here are my operational recommendations:

Use layered caching for multi-instance deployments. The hot-hit latency is identical to memory-only (~0.005ms), but you get distributed consistency and stampede prevention.
Warm your cache before traffic spikes. Cold misses under slow Redis are painful (~2.5s), and dead Redis won't gracefully degrade for new keys.
Set generous L1 limits for large payloads. 1MB objects in Redis are 200x slower than in memory. Let L1 absorb that cost.
Don't rely on graceful degradation for cold keys. It protects hot L1 traffic during outages, but new keys will still timeout.
Trust the stampede prevention. The library correctly handled 75→1 fetch reduction even with TTL expiry and cross-instance coordination.

Getting Started

Basic setup:

import { CacheStack, MemoryLayer, RedisLayer } from 'layercache'
import Redis from 'ioredis'

const cache = new CacheStack([
  new MemoryLayer({ ttl: 60, maxSize: 10_000 }),
  new RedisLayer({ client: new Redis(), ttl: 3600 })
])

// Automatic stampede prevention
const user = await cache.get('user:123', () => db.findUser(123))

For distributed deployments, wire up the invalidation bus:

import { RedisInvalidationBus, RedisSingleFlightCoordinator } from 'layercache'

const cache = new CacheStack([
  new MemoryLayer({ ttl: 60 }),
  new RedisLayer({ client: redis })
], {
  invalidationBus: new RedisInvalidationBus({ 
    publisher: redis, 
    subscriber: new Redis() 
  }),
  singleFlightCoordinator: new RedisSingleFlightCoordinator({ client: redis }),
  gracefulDegradation: { retryAfterMs: 10_000 }
})

The Verdict

layercache delivers on its promises. The benchmark data shows it handles the three hard problems of production caching—stampede prevention, graceful degradation, and distributed consistency—without sacrificing the performance of simple in-memory caching.

The 100x HTTP throughput improvement and zero-fetch stampede protection make it a strong candidate for any Node.js service moving beyond a single instance.

Have you solved cache stampedes differently? I'd love to hear your war stories in the comments.

Links:

npm: layercache
GitHub Repository
Benchmark environment: Node.js v20.20.1, Redis 7-alpine, Linux 5.15

I built a multi-layer caching library for Node.js — would love your feedback!

날다람쥐 — Wed, 08 Apr 2026 17:51:00 +0000

Hey dev.to community! 👋

I've been working on a side project for a while now and finally got it to a point where I feel comfortable sharing it publicly. It's called layercache — a multi-layer caching toolkit for Node.js.

I'd really appreciate any feedback, honest criticism, or ideas from folks who deal with caching in production. Here's the quick overview:

Why I built this

Almost every Node.js service I've worked on eventually hits the same caching problem:

Memory-only cache → Fast, but each instance has its own isolated view of data
Redis-only cache → Shared across instances, but every request still pays a network round-trip
Hand-rolled hybrid → Works at first, then you need stampede prevention, tag invalidation, stale serving, observability... and it spirals fast

I couldn't find a library that handled all of this cleanly in one place, so I built one.

What layercache does

layercache lets you stack multiple cache layers (Memory → Redis → Disk) behind a single unified API. On a cache hit, it serves from the fastest available layer and backfills the rest. On a miss, the fetcher runs exactly once — even under high concurrency.

              ┌───────────────────────────────────────┐
your app ---->│             layercache                │
              │                                       │
              │  L1 Memory    ~0.01ms  (per-process)  │
              │      |                                │
              │  L2 Redis     ~0.5ms   (shared)       │
              │      |                                │
              │  L3 Disk      ~2ms     (persistent)   │
              │      |                                │
              │  Fetcher      ~20ms    (runs once)    │
              └───────────────────────────────────────┘

Basic usage

npm install layercache

import { CacheStack, MemoryLayer, RedisLayer } from 'layercache'
import Redis from 'ioredis'

const cache = new CacheStack([
  new MemoryLayer({ ttl: 60, maxSize: 1_000 }),       // L1: in-process
  new RedisLayer({ client: new Redis(), ttl: 3600 }),  // L2: shared
])

// Read-through: fetcher runs once, all layers filled automatically
const user = await cache.get('user:123', () => db.findUser(123))

You can also start with just memory (no Redis required) and add layers as your needs grow.

Key features I'm most proud of

Stampede prevention — 100 concurrent requests for the same key trigger only 1 fetcher execution. Distributed dedup via Redis locks works across multiple server instances too.

Tag-based invalidation — Invalidate groups of related keys by tag, including across all layers at once. Useful for things like "invalidate all user-related cache entries."

Stale-while-revalidate / stale-if-error — Serve the stale cached value immediately while refreshing in the background, or keep serving stale data when the upstream is down.

Framework integrations — Middleware helpers for Express, Fastify, Hono, tRPC, GraphQL, and a NestJS module with a @Cacheable() decorator.

Observability out of the box — Prometheus exporter, OpenTelemetry tracing, per-layer latency metrics, event hooks, and an HTTP stats endpoint.

Admin CLI — npx layercache stats|keys|invalidate for Redis-backed caches.

NestJS example (because I use NestJS a lot)

// app.module.ts
@Module({
  imports: [
    CacheStackModule.forRoot({
      layers: [
        new MemoryLayer({ ttl: 20 }),
        new RedisLayer({ client: redis, ttl: 300 })
      ]
    })
  ]
})
export class AppModule {}

// user.service.ts
@Injectable()
export class UserService {
  constructor(@InjectCacheStack() private readonly cache: CacheStack) {}

  async getUser(id: number) {
    return this.cache.get(`user:${id}`, () => this.db.findUser(id))
  }
}

Benchmark numbers (on my machine, grain of salt)

Scenario	Avg Latency
L1 memory hit	~0.006 ms
L2 Redis hit	~0.020 ms
No cache (simulated DB)	~1.08 ms

Stampede prevention: 100 concurrent requests → 1 fetcher execution.

What I'm looking for feedback on

Honestly, everything! But a few things I'm specifically unsure about:

API design — Does the CacheStack + layer composition model feel intuitive? Are there footguns I'm missing?
The feature set — Is this too much? Too little? Are there things here that should just be separate libraries?
Production readiness — What would you need to see before using something like this in production? (more tests? better docs? battle-tested examples?)
Naming / discoverability — layercache as a name... does it communicate what it does clearly enough?
Anything else — I'm sure there are patterns or edge cases I haven't thought of.

DEV Community: 날다람쥐

I tried every TypeScript Result library. So I built a better one.

The problem, quickly

Why not the existing libraries?

neverthrow

true-myth

ts-results

result.ts

What verdict-ts does differently

The full API

Real-world example: API client

Quick comparison table

Install

I got tired of AI agents trashing my codebase, so I built a skill to fix that

What it actually does

The "respect existing code" problem

Solving the infinite debugging loop

Works on 8 platforms, install in one line

Reference files included

What vibe coding this taught me

Getting started

I got tired of deploying broken configs, so I built dotenv-scan

What it does

The three problems it catches

Plugging it into CI

Auto-generating .env.example

Multi-language support

The interesting part: detecting dynamic access

Architecture in one diagram

Zero runtime dependencies (almost)

Getting started

I Audited My Own Open Source Library and Found 9 Security Bugs. Here's Every One.

Why I did a full security audit

VULN-1 (HIGH): Unbounded memory growth in keyEpochs

VULN-2 (MED-HIGH): Unbounded queue in FetchRateLimiter

VULN-3 (MEDIUM): CLI accepted unvalidated input before hitting Redis

VULN-4 (MEDIUM): invalidate could wipe the entire cache with no confirmation

VULN-5 (MEDIUM): TagIndex pruning was silently broken

VULN-6 (MEDIUM): TOCTOU race in snapshot file writes

VULN-7 (LOW): Memory leak in layerDegradedUntil

VULN-8 (LOW): Math.random() for TTL jitter

VULN-9 (LOW): Background refresh failures logged at debug level

What I learned from this

Upgrade

I got tired of wiring the same caching stack every project, so I built LayerCache

What it does

Solving the stampede problem

Keeping L1 caches in sync across instances

When Redis dies

Benchmark numbers

Warm hit latency

HTTP throughput (autocannon, 40 connections, 8 seconds)

Memory pressure

Other things it does

Getting started

useless-gps

What I Built

Demo

Code

flyingsquirrel0419 / useless-gps

useless-gps

Stack

Local Development

How It Works

Contribution Policy

Operator Review

How I Built It

Prize Category

layercache: Stop Paying Redis Latency on Every Hot Read

The Core Idea

Getting Started

Benchmark Results

Warm Hit Latency

Stampede Prevention

HTTP Throughput

What Happens When Redis Is Slow or Dead?

Slow Redis

Dead Redis

Queue Amplification Under Slow Redis

Memory Pressure and Eviction

Auto-generating `.env.example`

VULN-1 (HIGH): Unbounded memory growth in `keyEpochs`

VULN-2 (MED-HIGH): Unbounded queue in `FetchRateLimiter`

VULN-4 (MEDIUM): `invalidate` could wipe the entire cache with no confirmation

VULN-5 (MEDIUM): `TagIndex` pruning was silently broken

VULN-7 (LOW): Memory leak in `layerDegradedUntil`

VULN-8 (LOW): `Math.random()` for TTL jitter

VULN-9 (LOW): Background refresh failures logged at `debug` level