Registry / storage / etag-cache-leveldb

etag-cache-leveldb

library2.1.17jsnpmunverified

A persistent HTTP ETag cache backed by LevelDB for Node.js. Current stable version is 2.1.17. It uses levelup and leveldown (or any abstract-leveldown-compatible store) to persist ETags and response bodies, enabling conditional requests (If-None-Match) and caching of fetch responses. It reconstructs Response-like objects when a cached entry matches. Key differentiators: direct integration with fetch API responses, simple key-value design (URL→ETag and ETag→body), and support for custom LevelDB instances. Release cadence is irregular as a side project.

storage

npm install etag-cache-leveldb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ETAG-CACHE-LEVELDB

etag-cache-leveldb

storagejavascriptv2.1.17

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.

ETagCacheLevelDB

✓ import { ETagCacheLevelDB } from 'etag-cache-leveldb'

✗ const ETagCacheLevelDB = require('etag-cache-leveldb');

Package exports ES module. Use named import.

ETagCacheLevelDB

✓ const { ETagCacheLevelDB } = await import('etag-cache-leveldb')

Dynamic import works as well.

ETagCacheLevelDB

✓ import type { ETagCacheLevelDB } from 'etag-cache-leveldb'

Type import for TypeScript when only using types.

rawTagData

✓ import { rawTagData } from 'etag-cache-leveldb'

✗ const rawTagData = require('etag-cache-leveldb').rawTagData;

rawTagData is a helper function for internal use but exported.

Demonstrates creating a LevelDB-backed ETag cache, storing a response, adding conditional headers, and loading a cached response on 304.

import levelup from 'levelup'; import leveldown from 'leveldown'; import { ETagCacheLevelDB } from 'etag-cache-leveldb'; const db = await levelup(leveldown('./leveldb-cache')); const cache = new ETagCacheLevelDB(db); const url = 'https://api.example.com/data'; const response = await fetch(url); await cache.storeResponse(response); const headers = {}; const etagFound = await cache.addHeaders(url, headers); if (etagFound) { const conditionalResponse = await fetch(url, { headers }); if (conditionalResponse.status === 304) { const cachedResponse = await cache.loadResponse(conditionalResponse); const body = await cachedResponse.text(); console.log('Cached body:', body); } }

Debug

Known issues

gotchastoreResponse() expects a Response object; passing a fetch Response with a non-cloned body may consume the stream.

fix

Clone the response before storing if you intend to read its body elsewhere: response.clone()

affects: all

gotchaaddHeaders() modifies the headers object in place.

fix

Pass a mutable headers object (e.g., new Headers() or a plain object).

affects: all

deprecatedThe LevelDB backend must be provided via levelup; the package does not support sublevel or multiple databases without manual setup.

fix

Ensure you create a separate LevelDB instance per cache instance.

affects: all

breakingThe constructor expects a prepared levelup instance; passing a raw levelup factory or leveldown instance will fail.

fix

Always call levelup(leveldown(path)) before passing to ETagCacheLevelDB.

affects: >=2.0.0

gotchaloadResponse() only works if the response has an ETag header and the ETag matches a stored body; otherwise it throws.

fix

Check response status 304 or use addHeaders() first. Ensure response.headers.get('ETag') is present.

affects: all

Errors

Common errors & fixes

TypeError: db.put is not a function

Passing a raw leveldown instance instead of a levelup instance

fix

const db = levelup(leveldown('/path'));

Error: ETag not found in cache

Calling loadResponse() on a response that doesn't have a matching ETag or was not stored

fix

Check that the response has an ETag header and that storeResponse() was called earlier for the same URL.

TypeError: Cannot read properties of undefined (reading 'headers')

Passing undefined or null to addHeaders instead of a headers object

fix

Ensure headers parameter is an object (e.g., new Headers() or {}).

Upgrade

Version history

2.1.17latest on npm

Audit

Dependencies

leveluprequiredCore dependency for LevelDB interface

leveldownoptionalDefault LevelDB backend (can be replaced with other abstract-leveldown-compatible stores)

Agent activity

28 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/arlac77/etag-cache-leveldb ↗

packageetag-cache-leveldb ↗

homepagehttps://github.com/arlac77/etag-cache-leveldb#readme ↗