DEV Community: 날다람쥐

claude-occ: Use Claude Code with Your Own Provider Gateway

날다람쥐 — Thu, 09 Jul 2026 15:00:36 +0000

claude-occ: Use Claude Code with Your Own Provider Gateway

I built claude-occ, a local gateway proxy that lets Claude Code route requests through your own providers while keeping the normal claude workflow.

GitHub: https://github.com/flyingsquirrel0419/claude-occ

npm: https://www.npmjs.com/package/claude-occ

If this looks useful, a GitHub star would help the project reach more Claude Code users:

⭐ https://github.com/flyingsquirrel0419/claude-occ

What is claude-occ?

claude-occ installs an occ command that runs a local Claude Code-compatible gateway.

Claude Code talks to a local occ daemon through the Anthropic Messages API, and occ routes requests to configured providers such as:

Anthropic-compatible APIs
OpenAI-compatible APIs
OpenRouter
Google Gemini API
Azure OpenAI
local servers like Ollama, vLLM, or LM Studio
custom OpenAI-compatible endpoints

The goal is simple:

npm install -g claude-occ
occ init
claude

Why I made it

I liked the idea behind opencodex, but Claude Code has a different integration surface.

opencodex targets Codex and /v1/responses.

claude-occ targets Claude Code and /v1/messages.

Claude Code already speaks the Anthropic Messages API, so a local authenticated gateway can sit between Claude Code and the provider you actually want to use.

What it does

claude-occ can:

start a local gateway on 127.0.0.1
expose configured models through /v1/models
show routed provider models in Claude Code's /model picker
route /v1/messages to supported upstream APIs
install a Claude launcher shim so claude auto-starts the proxy
restore native Claude Code behavior with occ native
keep config in ~/.claude-occ/config.json
store provider keys directly or as environment-variable references

Example model IDs look like this:

openrouter/anthropic/claude-sonnet-5
umans/umans-coder
local/llama3

Important security boundary

Claude Code subscription OAuth stays native-only.

claude-occ does not extract, forward, or reuse Claude Code subscription tokens as upstream credentials.

If you want Claude Code's built-in subscription mode, run:

occ native

That stops the proxy and restores native Claude Code behavior.

Installation

Install from npm:

npm install -g claude-occ

Then run:

occ init

Start Claude Code normally:

claude

The npm package is intentionally small. During install, it detects your OS and CPU architecture, then downloads the matching native occ binary from GitHub Releases.

Supported binaries include Linux, macOS, and Windows for x64 and arm64.

Common commands

occ init
occ start
occ ensure
occ stop
occ restart
occ status
occ health
occ env
occ enable
occ native
occ restore back
occ uninstall
occ provider list
occ provider add openrouter --api-key '${OPENROUTER_API_KEY}' --set-default
occ models

Current limitations

This is a first public release, so some compatibility commands are intentionally lightweight:

occ gui currently prints the local dashboard URL.
occ service is compatibility-mode behavior, not a full OS service manager.
occ sync-cache is a no-op because Claude Code does not expose the same writable model cache pattern as Codex.

I would rather document those limits clearly than pretend everything is finished.

Try it and give feedback

If you use Claude Code and want to route it through your own providers, try it:

npm install -g claude-occ
occ init
claude

GitHub repo:

https://github.com/flyingsquirrel0419/claude-occ

If the project seems useful, please leave a star. It helps a lot with visibility and makes it easier to find early users who can test providers, report edge cases, and suggest better defaults.

⭐ https://github.com/flyingsquirrel0419/claude-occ

Feedback, issues, and provider compatibility reports are welcome.

I turned a Claude Code-only web reader into a normal MCP server

날다람쥐 — Tue, 07 Jul 2026 14:26:13 +0000

I kept running into the same problem while building with agents:

The page is public. A browser can read it. But my agent gets blocked, redirected, rate-limited, or handed a shell of HTML with no useful content.

There was already a fun project in this space: insane-search. It is clever, aggressive, and useful, but the original workflow is centered around Claude Code.

I wanted the same kind of public-web resilience as a regular MCP server, so any MCP-compatible client could call it.

That became unlimited-search.

flyingsquirrel0419 / unlimited-search

MCP server and CLI for reading public web pages through resilient public routes.

unlimited-search

English | 한국어 | 中文 | 日本語 | Español

From public pages to usable signal.

unlimited-search is a Python CLI and MCP server for reading public web content when a normal direct fetch is not enough. It combines platform public routes, browser-like HTTP identities, content fallbacks, public archive fallbacks, and media metadata extraction behind one local tool.

It is built for agents and automation that need usable text from public URLs. It is not intended to bypass logins, paywalls, CAPTCHA, private networks, account restrictions, IP bans, or access controls.

Quickstart

Prerequisite: Python 3.12 or newer.

python -m pip install unlimited-search
unlimited-search read https://en.wikipedia.org/wiki/OpenAI --max-content-chars 800

The command returns JSON with page content, a verdict, request metadata, and an attempt trace.

For MCP clients, install the package and register the stdio server:

{
  "mcpServers": {
    "unlimited-search": {
      "command": "unlimited-search"
      "args"

…

View on GitHub

TL;DR

unlimited-search is a Python CLI and MCP server for reading public web pages through multiple public routes and fallbacks.

It can:

read one public URL
read many public URLs in one MCP call
diagnose why a page is hard to access
extract public media metadata with yt-dlp
fall back through public platform routes, browser-like HTTP fetching, public archives, feeds, and metadata extraction

It does not try to bypass logins, paywalls, CAPTCHA, private networks, account restrictions, or real access controls.

Install

python -m pip install unlimited-search

Then add it to your MCP client:

{
  "mcpServers": {
    "unlimited-search": {
      "command": "unlimited-search",
      "args": ["serve"]
    }
  }
}

Restart your MCP client and you should get these tools:

read_public_url
read_public_urls
diagnose_access
extract_media

Quick test

You can also use it directly from the terminal:

unlimited-search read https://example.com --max-content-chars 1000
unlimited-search diagnose https://example.com

The output is JSON with the recovered content, final URL, verdict, metadata, and a trace of what was attempted.

Why I built it

Most agents are good at reasoning over text once the text is in context.

The annoying part is getting the text.

Modern public websites are not consistent:

some have useful public APIs
some render almost everything client-side
some expose RSS or Atom feeds
some have Open Graph or JSON-LD metadata but thin HTML
some work only with a browser-like TLS identity
some are easier to read through a public archive snapshot
some media pages are better handled as metadata, not raw HTML

So instead of pretending every URL is the same, unlimited-search tries a layered strategy.

How it works

For a URL, the reader tries the least invasive public route first:

Platform-specific public routes for sites like Reddit, X/Twitter, YouTube metadata, Bluesky, Mastodon, Hacker News, Stack Overflow, Wikipedia, GitHub, npm, PyPI, Naver Blog, Google Scholar, Amazon, and more.
Browser-like HTTP fetching with multiple identities, URL variants, referer strategies, and HTTP transport fallback.
Content fallbacks such as Jina Reader JSON, RSS/Atom discovery, common feed paths, OGP, JSON-LD, Schema.org, and Next.js metadata.
Public archive fallbacks through Wayback and archive.today/archive.ph best-effort snapshots.
Media metadata extraction through yt-dlp for public media URLs.

Every result includes a verdict:

strong_ok: a high-confidence public route worked
weak_ok: content was recovered, but may be partial or fallback-based
suspect_ok: something useful was found, but the caller should inspect it
failure verdicts for blocked, unsafe, login-only, CAPTCHA, private-network, or unusable results

Example MCP call

Ask your MCP client something like:

Use unlimited-search to read this public URL and summarize the page:
https://example.com

Behind the scenes, the model can call:

{
  "url": "https://example.com",
  "max_content_chars": 4000
}

And get back content plus a trace, not just a silent failure.

What makes it different from a normal fetch?

A normal fetch asks:

Can I GET this URL?

unlimited-search asks:

Is there a legitimate public route to useful text for this URL?

That difference matters for agent workflows.

If the direct HTML fetch is bad, the tool can try a public API. If the page is metadata-rich but content-light, it can salvage metadata. If the live page is flaky, it can try public archive routes. If the page is media, it can return structured media metadata instead of dumping a giant HTML shell.

The goal is not to be magical. The goal is to be practical.

Safety boundary

This is important: unlimited-search is a public-content reader.

It is designed to stop when the target requires:

authentication
payment
CAPTCHA
private network access
account-specific authorization
hard anti-abuse bypassing

It also rejects private, loopback, link-local, multicast, reserved, and metadata-service targets by default.

That boundary makes the tool useful for agents without turning it into a bypass tool.

The insane-search inspiration

I like the spirit of insane-search: make public web reading less fragile for agent workflows.

The difference is packaging and interface.

Instead of keeping the workflow tied to one agent environment, unlimited-search exposes the capability as a regular MCP server:

install with pip
run over stdio
call from any MCP-compatible client
inspect traces and verdicts
use it as a CLI when you do not need MCP

That makes it easier to plug into different local agent setups.

Try it

python -m pip install unlimited-search
unlimited-search read https://dev.to --max-content-chars 1500

GitHub:

https://github.com/flyingsquirrel0419/unlimited-search

PyPI:

https://pypi.org/project/unlimited-search/

If this saves you from writing yet another fragile page-fetching tool, a GitHub star would help the project get discovered.

And if you test it against a weird public site, I would love to hear what worked, what failed, and what fallback should be added next.

Most apps do not need a full date library, so I built a 2KB one

날다람쥐 — Sun, 21 Jun 2026 07:56:53 +0000

Most frontend and Node.js apps need date utilities.

But in many projects, the actual needs are pretty small:

format a date
parse an ISO string
add a few days or months
compare two dates
get the start or end of a day/week/month
check weekends or leap years

For those common cases, pulling in a larger date library can feel heavier than necessary.

So I built date-light.

What is date-light?

date-light is a small, zero-dependency date utility library for TypeScript and JavaScript.

It provides 39 common date helpers in about 2.18KB minzipped.

npm install date-light
ts
import { addDays, differenceInDays, format, startOfWeek } from "date-light";

const launch = new Date(2026, 5, 30, 14, 30);
const reminder = addDays(launch, -7);

format(launch, "yyyy-MM-dd HH:mm");
// "2026-06-30 14:30"

format(startOfWeek(launch), "yyyy-MM-dd");
// "2026-06-29"

differenceInDays(launch, reminder);
// 7

You can also try it in the docs/playground site:

https://date-light.flyingsquirrel.me

Why I made it

I like date-fns. It has a great API and covers a huge range of date operations.

But most apps I work on only use a small subset of that surface area.

Common examples:

format(date, "yyyy-MM-dd");
parseISO("2026-01-15");
addDays(date, 7);
addMonths(date, 1);
differenceInDays(a, b);
startOfMonth(date);
endOfMonth(date);
isSameDay(a, b);

I wanted a tiny library that focused on those common operations and avoided everything else:

no locale system
no timezone database
no plugins
no chainable wrapper
no runtime dependencies

Just the date helpers most apps actually ship.

What it includes

date-light currently includes helpers for:

Area	Examples
Format & parse	`format`, `parseISO`, `parse`
Add & subtract	`addDays`, `addMonths`, `addYears`, `subDays`
Difference	`differenceInDays`, `differenceInMonths`, `differenceInYears`
Compare	`isBefore`, `isAfter`, `isEqual`, `isSameDay`
Query	`isWeekend`, `isLeapYear`, `isValid`, `getDaysInMonth`
Start & end	`startOfDay`, `startOfWeek`, `endOfMonth`, `endOfYear`

All functions are typed and return new Date instances instead of mutating the input.

import { addMonths } from "date-light";

const original = new Date(2026, 0, 31);
const next = addMonths(original, 1);

console.log(original);
// Jan 31, 2026

console.log(next);
// Feb 28, 2026

Handling date edge cases

Dates have a lot of sharp edges, so I added tests for the cases that usually cause problems.

For example, month-end clamping:

addMonths(new Date(2026, 0, 31), 1);
// Feb 28, 2026

addMonths(new Date(2024, 0, 31), 1);
// Feb 29, 2024

Leap years:

isLeapYear(new Date(2024, 0, 1));
// true

isLeapYear(new Date(1900, 0, 1));
// false

isLeapYear(new Date(2000, 0, 1));
// true

And date-only ISO parsing:

parseISO("2026-01-15");
// local midnight, matching date-fns behavior

Package support

The package ships with:

ESM
CommonJS
TypeScript declarations
zero runtime dependencies
tree-shakeable exports

The package entrypoints are tested before release.

Size

The current library build is about 2.18KB minzipped.

That is the main goal of the project: keep the useful common date helpers small enough that you do not have to think much about adding them.

What date-light is not

date-light is intentionally not a complete date platform.

It does not try to replace:

full date-fns
Luxon
Temporal
timezone-aware libraries
advanced locale formatting

If you need full i18n, timezone conversions, duration objects, or complex calendar logic, you should use a more complete library.

date-light is for the smaller common case:

“I just need the date helpers I use all the time.”

Try it

Docs and playground:

https://date-light.flyingsquirrel.me

GitHub:

https://github.com/flyingsquirrel0419/date-light

npm:

npm install date-light

Example:

import {
  format,
  parseISO,
  addDays,
  differenceInDays,
  startOfMonth,
  endOfMonth,
} from "date-light";

const date = parseISO("2026-06-30");

console.log(format(date, "yyyy-MM-dd"));
console.log(format(startOfMonth(date), "yyyy-MM-dd"));
console.log(format(endOfMonth(date), "yyyy-MM-dd"));
console.log(differenceInDays(addDays(date, 7), date));

If you try it, feedback is welcome.

And if you find the project useful, a GitHub star would help a lot:

https://github.com/flyingsquirrel0419/date-light

I built date-light: a tiny zero-dependency date utility for JavaScript

날다람쥐 — Sat, 06 Jun 2026 17:33:59 +0000

I built date-light, a small zero-dependency date utility library for JavaScript and TypeScript.

I wanted something focused on the common date operations I use most often: formatting, parsing, date math, comparisons, and start/end helpers, without pulling in a larger date library for simple use cases.

What it includes

39 date utility functions
Zero runtime dependencies
TypeScript types
ESM and CommonJS builds
date-fns-style format tokens
A docs/playground site for quickly trying the API

Playground

You can try it here:

https://date-light.flyingsquirrel.me/?v=20260607

Install

npm install date-light

It also works with:

yarn add date-light
pnpm add date-light
bun add date-light

Example

import { format, addDays, differenceInDays } from "date-light";

const today = new Date("2026-06-07T10:30:00");

console.log(format(today, "yyyy-MM-dd"));
console.log(format(addDays(today, 7), "yyyy-MM-dd"));
console.log(differenceInDays(new Date("2026-06-14"), today));

Why I made it

For many projects, I only need a focused set of date helpers:

Format a date for UI
Parse an ISO or pattern-based date string
Add or subtract days, months, years, hours, minutes, or seconds
Compare two dates
Snap dates to day, week, month, or year boundaries

I wanted the package to stay small, typed, and easy to evaluate before installing.

Links

Docs/playground:
https://date-light.flyingsquirrel.me/?v=20260607

GitHub:
https://github.com/flyingsquirrel0419/date-light

npm:
https://www.npmjs.com/package/date-light

I would love feedback on the API naming, date edge cases, and whether the playground/docs make the package easy to evaluate.

If you find the project useful, a GitHub star would also help other developers discover it.

date-light: A 1.8KB Alternative to date-fns You Might Actually Like

날다람쥐 — Sat, 30 May 2026 14:46:20 +0000

If you've ever shipped a frontend app and watched your bundle bloat because of date utilities, you're not alone. date-fns is fantastic — but importing 20 functions costs you 18 KB. dayjs is lighter at 3 KB, but it wraps every Date in a mutable object.

I wanted something different: pure functions, zero dependencies, and a bundle so small you forget it's there.

That's date-light.

What is it?

date-light is a zero-dependency, fully typed date utility library for JavaScript and TypeScript. It covers the 20 most-used date-fns operations with 39 functions — and the entire thing weighs 1.79 KB minzipped.

npm install date-light

import { format, addDays, differenceInDays, isBefore, startOfDay } from "date-light";

const date = new Date(2026, 5, 30, 14, 30, 45);

format(date, "yyyy-MM-dd HH:mm:ss"); // "2026-06-30 14:30:45"
addDays(date, 7); // Tue Jul 07 2026
differenceInDays(date, new Date(2026, 0, 1)); // 180
isBefore(date, new Date()); // true
startOfDay(date); // Mon Jun 30 2026 00:00:00

Same pattern syntax as date-fns. Most projects can migrate with a single import change.

Why not just use date-fns?

You absolutely can, and if you need all 252 functions, you should. But for most projects, you use maybe 15-20. Here's what that costs:

Library	minzipped	What you get
date-light	1.79 KB	39 functions, fully tree-shakeable
dayjs	2.97 KB	Core only (plugins add more)
date-fns (20 functions)	18.34 KB	Just the 20 most-used functions
date-fns (full)	261.3 KB	All 252 functions

That's a 10x size difference for the same functionality most people actually use.

How fast is it?

Benchmarks on Node.js 24 — nanoseconds per operation (lower = better):

vs date-fns v4

Function	date-light	date-fns
`format`	668 ns	1,495 ns	2.2x faster
`parseISO`	138 ns	1,218 ns	8.8x faster
`differenceInDays`	117 ns	946 ns	8.1x faster
`isWeekend`	4 ns	39 ns	9.8x faster
`isLeapYear`	5 ns	41 ns	8.2x faster
`startOfDay`	47 ns	49 ns	~same

vs dayjs v1

Function	date-light	dayjs
`addDays`	80 ns	642 ns	8x faster
`addMonths`	133 ns	2,067 ns	15.5x faster
`isBefore`	56 ns	531 ns	9.5x faster

Why so fast? date-light calls native Date methods directly. No wrapper objects (dayjs), no shared internal modules (date-fns). Pure functions with zero overhead.

What's included?

Format & Parse: format, parseISO, parse

Add & Subtract: addDays, addMonths, addYears, addHours, addMinutes, addSeconds, subDays, subMonths, subYears, subHours, subMinutes, subSeconds

Difference: differenceInDays, differenceInHours, differenceInMinutes, differenceInSeconds, differenceInMonths, differenceInYears

Compare: isBefore, isAfter, isEqual, isSameDay, isSameMonth

Query: isWeekend, isLeapYear, isValid, getDaysInMonth, getWeekOfYear

Start & End: startOfDay, endOfDay, startOfWeek, endOfWeek, startOfMonth, endOfMonth, startOfYear, endOfYear

Design decisions

date-fns compatible pattern syntax. yyyy-MM-dd, not YYYY-MM-DD. If you're migrating from date-fns, most code works as-is.

Pure functions, immutable. Every function returns a new Date. No mutation, no surprises.

Named exports only. No default export, no class instances. Tree-shaking works perfectly out of the box.

Month clamping matches date-fns. addMonths(new Date(2026, 0, 31), 1) returns Feb 28, not Mar 3. Same behavior you'd expect.

Calendar days vs physical time. addDays uses calendar-day semantics (preserves time-of-day across DST). addHours uses physical time (exact N hours later). This is the correct behavior — and it's what date-fns does too.

Migration from date-fns

One import change:

- import { format, addDays, differenceInDays } from 'date-fns';
+ import { format, addDays, differenceInDays } from 'date-light';

That's it. Same function names, same arguments, same pattern tokens.

Your GitHub Profile README Is Boring. Here's How to Fix It with SVG and GitHub Actions.

날다람쥐 — Tue, 12 May 2026 12:04:15 +0000

Most GitHub profiles look like this:

# Hi, I'm John 👋
I'm a developer who likes coding.

And that's it. A plain heading, maybe a bullet list of tech, nothing else.

Your profile is the first thing a recruiter, collaborator, or fellow developer sees when they look you up. You've got about three seconds to make an impression. A wall of plain Markdown isn't making one.

Here's what the good profiles have in common: animated headers, auto-updating stats, and dynamic content that actually runs on GitHub's own infrastructure — all via GitHub Actions, no external servers required.

I put together a repo that walks you through exactly how to do this, step by step.

What You Can Build

Here's what a finished profile can include — all generated automatically:

An animated gradient header banner (updates on every page load)
A typing animation for your intro line
Auto-updating stat cards: commits, stars, PRs, streak
A language breakdown chart
A tech stack badge grid
A snake animation that eats your actual contribution graph
Custom GitHub Actions that pull in blog posts, WakaTime stats, weather — anything with an API

No design skills required. Every piece is copy-paste ready.

The Tools

These are the services that power the best GitHub profiles. They're all free.

capsule-render — generates animated header banners via a single <img> tag. Waving gradients, glitch effects, colorful text. You just pass URL parameters.

![header](https://capsule-render.vercel.app/api?type=waving&color=gradient&height=200&text=Hello%20World&animation=fadeIn)

readme-typing-svg — same idea, but for typing animations. Pass your lines of text as URL params, get back an SVG that types them out in sequence.

![Typing SVG](https://readme-typing-svg.demolab.com?font=Fira+Code&lines=Software+Engineer;Open+Source+Enthusiast;Always+learning)

github-readme-stats — stat cards for your profile. Languages, commit counts, streaks. Hosted, free, just put your username in the URL.

![Stats](https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=tokyonight)

lowlighter/metrics — the more powerful alternative. Runs as a GitHub Action inside your profile repo, generates a full metrics image, and commits it back automatically. Supports dozens of plugins: calendar heatmap, achievements, languages over time, and more.

Platane/snk — generates a snake animation that eats the squares on your contribution graph. Also a GitHub Action. Runs on a schedule, commits the SVG, you embed it in your README.

shields.io — clean, consistent badges for tech stack, social links, build status, anything.

How GitHub Actions Makes This Dynamic

Here's the part that makes this more interesting than a static README.

GitHub lets you create a repository with the same name as your username. Whatever README is in that repo gets displayed on your profile page. That's the trick everyone knows.

What fewer people do is run GitHub Actions inside that repo on a schedule.

A workflow like this runs every day at midnight:

name: Update Profile
on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate metrics
        uses: lowlighter/metrics@latest
        with:
          token: ${{ secrets.METRICS_TOKEN }}
          filename: metrics.svg
          base: header, activity, community, repositories
      - name: Commit changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add metrics.svg
          git diff --cached --quiet || git commit -m "chore: update metrics"
          git push

Your profile README then just references metrics.svg as a normal image. Every day it's fresh. No server. No hosting. GitHub does the compute for free.

Three Templates to Start From

Rather than building from scratch, the repo includes three starting points:

Minimal — capsule-render header, typing SVG intro, shields.io badges, one stats card. Clean and professional. Good if you want something polished without the maintenance overhead of Actions.

Developer — everything in Minimal plus a streak card, language breakdown, and activity section. More visual, still no Actions required.

Advanced — the full setup. GitHub Actions for auto-updating metrics, the snake animation workflow, and a custom Action that pulls in your latest blog posts. This is the one that makes people ask "how did you do that."

Quick Start

Three steps:

1. Create your profile repo. New repository, name it exactly the same as your GitHub username. Initialize with a README. GitHub recognizes this automatically and displays it on your profile.

2. Pick a template. Go to profiles/ and copy the README from whichever template fits. Paste it into your profile repo's README.

3. Swap in your username. Every YOUR_USERNAME placeholder gets replaced with your actual username. Push, and you're live.

The guides in the repo walk through each piece in detail — from the initial repo setup through writing your own custom GitHub Actions.

The Repo

Everything covered here — guides, templates, copy-paste snippets, workflow files — is at:

github.com/flyingsquirrel0419/awesome-git-profile

If it's useful, a ⭐ on the repo helps other developers find it. There's also a community showcase — once your profile is set up, submit a PR to add it.

The guides go in order from zero to a finished profile, but they're also written to be standalone. If you just need the snake animation, go straight to guide 06. If you want to write a custom Action that fetches your latest blog posts, guide 08 covers that.

Happy building.

Layercache 2.0.0: Millisecond TTLs, Stale-Preserving Expiration, and Better Redis Coverage

날다람쥐 — Fri, 01 May 2026 18:22:10 +0000

Layercache 2.0.0 is out.

This release is intentionally a major version because it changes the public TTL semantics from seconds to milliseconds. That is a breaking change, but it also makes Layercache much more consistent with Node.js timers, Redis PX / PTTL, and most JavaScript runtime APIs.

What changed?

Breaking: TTL values are now milliseconds

Before 2.0.0, TTL examples and parts of the public API used seconds.

In 2.0.0, TTL-related values are consistently milliseconds:

const cache = new CacheStack({
  layers: [memory, redis],
  ttl: 60_000
})

await cache.set("user:1", user, {
  ttl: 30_000,
  staleWhileRevalidate: 120_000,
  staleIfError: 300_000
})

This applies to:

layer defaults
operation-level ttl
negativeTtl
staleWhileRevalidate
staleIfError
ttlJitter
refreshAhead
adaptive TTL policies
TTL policy return values

Redis writes now use PX, Redis TTL reads use PTTL, and CLI inspect output reports ttlMs.

New stale-preserving expiration APIs

Layercache 2.0.0 adds expiration APIs that mark entries stale without deleting their stale windows:

await cache.expireByTag("product")
await cache.expireByTags(["product", "pricing"])
await cache.expireByPattern("product:*")
await cache.expireByPrefix("product:")

This is useful when you want revalidation to happen, but still want existing cached values to be served during stale-while-revalidate or stale-if-error windows.

Instead of forcing a hard delete, these APIs let the cache degrade more gracefully.

Context-aware cache entry options

contextOptions can now derive TTLs and tags from the resolved cache context:

const cache = new CacheStack({
  layers: [memory],
  contextOptions: ({ key, value, kind }) => ({
    ttl: kind === "set" ? 30_000 : 60_000,
    tags: value.orgId ? [`org:${value.orgId}`] : []
  })
})

This works for fetched values and direct set() calls.

It makes it easier to keep cache metadata close to the data being cached.

Better Redis integration coverage

This release adds real Redis integration coverage for:

RedisLayer
RedisInvalidationBus
RedisTagIndex
distributed single-flight
multi-instance behavior
millisecond TTL handling

The integration suite now runs against a real Redis service through Docker Compose.

Documentation site

Layercache now includes a Next.js docs site with:

MDX docs
search
playground
markdown export
sitemap
robots.txt
.well-known API and agent metadata routes

Docs are available at:

https://layercache.flyingsquirrel.me

Smaller npm package

The npm package is now limited to runtime build artifacts.

The package includes:

dist/
package.json
README.md
LICENSE

Benchmarks, examples, and stale build artifacts are excluded from the published package.

Migration guide

The main migration step is converting TTL values from seconds to milliseconds.

Before:

ttl: 60
staleWhileRevalidate: 300
staleIfError: 600

After:

ttl: 60_000
staleWhileRevalidate: 300_000
staleIfError: 600_000

If you previously used numeric TTLs, audit every TTL-related option before upgrading.

Install

npm install layercache@2.0.0

Release notes

Full release notes are available here:

https://github.com/flyingsquirrel0419/layercache/releases/tag/v2.0.0

Support the project

If Layercache looks useful, please consider giving the repository a star on GitHub:

https://github.com/flyingsquirrel0419/layercache

Closing

Layercache 2.0.0 is a breaking release, but the goal is simple: make TTL behavior explicit, consistent, and easier to reason about across memory, Redis, disk, CLI output, and documentation.

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.