koa-cash

library5.0.2jsnpmunverified

HTTP response caching middleware for Koa (v5.0.2, requires Node >=18). Supports any store (memory, Redis, etc.) via async get/set functions. Handles JSON/stream bodies, gzip compression (opt-in since v4), and 304 responses. Differentiator: minimal, store-agnostic design compared to heavier solutions like koa-response-cache. Pairs well with @ladjs/koa-cache-responses for advanced caching. Active development with periodic releases.

caching web

npm install koa-cash

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOA-CASH

koa-cash

cachingjavascriptv5.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import koaCash from 'koa-cash'

✗ const koaCash = require('koa-cash')

ESM-only since v3; CommonJS require will fail in Node >=18 unless using .mjs or --experimental-modules. TypeScript: use allowSyntheticDefaultImports or esModuleInterop.

default (CJS workaround)

✓ const koaCash = (await import('koa-cash')).default

✗ const koaCash = require('koa-cash').default

For CJS projects, dynamic import is needed. The package does not export a CJS entrypoint.

Shows ESM import, store setup with get/set using Map, and ctx.cashed() pattern for caching responses. Uses TypeScript type assertions.

import Koa from 'koa'; import koaCash from 'koa-cash'; const app = new Koa(); // In-memory store (simple example) const store = new Map(); app.use(koaCash({ get(key) { return Promise.resolve(store.get(key) || null); }, set(key, value) { store.set(key, value); return Promise.resolve(); }, maxAge: 30000 // 30 seconds })); app.use(async (ctx) => { if (await ctx.cashed()) return; ctx.body = { message: 'Hello World', date: Date.now() }; }); app.listen(3000, () => console.log('Running on port 3000'));

Debug

Known issues

breakingkoa-cash v3 switched to ESM-only. CommonJS require() throws an error.

fix

Use dynamic import or switch to ES modules. If using TypeScript, set type: 'module' or use .mts.

affects: >=3.0.0

deprecatedThe 'compression' option default changed from true to false in v4.0.0.

fix

Pass { compression: true } explicitly if you need gzip compression.

affects: >=4.0.0

gotchamaxAge per-key is not automatically handled; you must implement it in get/set. The value 0 indicates no expiration.

fix

Check maxAge parameter in get/set and apply TTL in your store (e.g., lru-cache maxAge option).

affects: all

gotchaIf using ctx.cashed() with a maxAge argument, that overrides the global maxAge only for that request.

fix

Pass maxAge as second argument: await ctx.cashed(60000) to set a 60-second TTL.

affects: all

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/koa-cash/index.js from /path/to/app.js not supported.

Package is ESM-only; CJS require() is not supported since v3.

fix

Use `import koaCash from 'koa-cash'` or dynamic import `const koaCash = (await import('koa-cash')).default`.

TypeError: ctx.cashed is not a function

Middleware was not applied before the route handler, or the import/require failed silently.

fix

Ensure app.use(koaCash(...)) is called before any routes that use ctx.cashed(). Check that import/require is correct.

UnhandledPromiseRejectionWarning: Error: Not supported for no-cache or if-modified-since

The request has no-cache or conditional headers that bypass caching; ctx.cashed() returns false.

fix

This is expected behavior. Ensure your downstream middleware handles the case when ctx.cashed() returns false.

Upgrade

Version history

5.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/koajs/cash ↗

packagekoa-cash ↗

homepagehttps://github.com/koajs/cash ↗