receptacle

library1.3.2jsnpmunverified

In-memory LRU cache with TTL support for Node.js and browsers. Current stable version is 1.3.2, released under an MIT license with a stable API. It provides a simple API similar to Map but with LRU eviction and per-key TTL, optional refresh on access, and built-in serialization/deserialization to JSON. Differentiates from libraries like lru-cache by its smaller footprint, TypeScript type definitions, and more straightforward API without external dependencies.

storage

npm install receptacle

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RECEPTACLE

receptacle

storagejavascriptv1.3.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.

Receptacle

✓ import Receptacle from 'receptacle'

✗ import { Receptacle } from 'receptacle'

This package exports a default class. In CommonJS, use const Receptacle = require('receptacle').

Receptacle

✓ const Receptacle = require('receptacle')

✗ const { Receptacle } = require('receptacle')

CommonJS require gives the constructor directly, not an object.

Receptacle (with types)

✓ import Receptacle from 'receptacle'

✗ import Receptacle from 'receptacle/Receptacle'

TypeScript types are included; use default import as shown. No need to access subpath.

Creates a cache with max 100 items, sets a key with TTL 1 second, retrieves it, checks existence, deletes, clears, and demonstrates serialize/deserialize.

import Receptacle from 'receptacle' const cache = new Receptacle({ max: 100 }) cache.set('key', 'value', { ttl: 1000 }) console.log(cache.get('key')) // 'value' console.log(cache.has('key')) // true cache.delete('key') cache.clear() // Serialization const serialized = JSON.stringify(cache) const restored = new Receptacle(JSON.parse(serialized))

Debug

Known issues

breakingIn version 1.0, the constructor no longer accepts a number for max items; use { max: number } instead.

fix

Change new Receptacle(100) to new Receptacle({ max: 100 }).

affects: >=1.0.0

deprecatedUsing the 'meta' method to retrieve metadata is supported but not recommended for new code; prefer storing metadata alongside the value.

fix

Access metadata via cache.get(key) and store it in the value itself.

affects: <1.3.0

gotchaThe 'get' method returns undefined for expired or missing keys, even if the stored value is undefined. Use 'has' to check existence.

fix

Call cache.has(key) before cache.get(key) if you need to distinguish between missing keys and stored undefined.

affects: >=1.0.0

gotchaWhen serializing to JSON, expired items are still included in the JSON string but will be filtered out when deserializing (since TTLs are preserved). This can cause unexpected file size if many keys have expired.

fix

Call cache.clearExpired() before serializing (if available) or manually remove expired entries.

affects: >=1.0.0

gotchaThe 'refresh' option for TTL only works if the key is accessed via 'get' before expiry. If you only call 'has' or iterate over the cache, the TTL is not refreshed.

fix

Always use cache.get(key) to trigger refresh on access.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Receptacle is not a constructor

Using named import { Receptacle } instead of default import (ESM) or destructuring require (CommonJS).

fix

Use 'import Receptacle from "receptacle"' for ESM or 'const Receptacle = require("receptacle")' for CommonJS.

Cannot read property 'max' of undefined

Passing an incorrect argument to the constructor, e.g., new Receptacle(100) instead of new Receptacle({ max: 100 }).

fix

Pass an options object: new Receptacle({ max: 100 })

Receptacle is not a function

Attempting to import { Receptacle } as named export in ESM; package exports default.

fix

Use default import: import Receptacle from 'receptacle'

TypeError: cache.set is not a function

Instantiating incorrectly, e.g., calling Receptacle() without 'new' (missing new keyword).

fix

Always instantiate with 'new': const cache = new Receptacle(...)

Upgrade

Version history

1.3.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/DylanPiercey/receptacle ↗

packagereceptacle ↗

homepagehttps://github.com/DylanPiercey/receptacle ↗