Registry / storage / single-user-cache

single-user-cache

library2.1.0jsnpmunverified

A fast, lightweight cache and batching library for single-user GraphQL requests, inspired by DataLoader. Version 2.1.0 is stable, MIT-licensed, and ships TypeScript types. It creates per-request cache instances that batch multiple calls to the same loader into a single async function invocation. Benchmarks show it is 3x faster than DataLoader. Supports object keys via safe-stable-stringify, configurable caching and batch sizes. Published to npm, actively maintained by mcollina.

storage testing

npm install single-user-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SINGLE-USER-CACHE

single-user-cache

storagejavascriptv2.1.0

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.

Factory

✓ import { Factory } from 'single-user-cache'

✗ const { Factory } = require('single-user-cache')

ESM and CommonJS both supported. For ESM, use import. For CJS, require works as well.

single-user-cache (default export)

✓ import singleUserCache from 'single-user-cache'

✗ const singleUserCache = require('single-user-cache')

Library exports a default export as well; it is the Factory class. Both named and default imports work.

Factory type

✓ import type { Factory } from 'single-user-cache'

TypeScript types are shipped. You can use import type for type-only imports.

Creates a factory, adds a loader, creates a per-request cache, and batches two calls.

import { Factory } from 'single-user-cache'; const factory = new Factory(); factory.add('fetchUser', { cache: true, maxBatchSize: undefined, }, async (queries, context) => { console.log(queries); // e.g., [1, 2] return queries.map(id => ({ id, name: `User ${id}` })); }); async function run() { const context = { requestId: 'abc' }; const cache = factory.create(context); const [user1, user2] = await Promise.all([ cache.fetchUser(1), cache.fetchUser(2), ]); console.log(user1, user2); } run().catch(console.error);

Debug

Known issues

gotchaThe cache instance is per-context. Do not reuse a cache across different requests, as it will share the same batch and cache state.

fix

Always call factory.create(newContext) for each new request context.

affects: >=1.0.0

gotchaIf cache is set to false, the loader will still batch but not cache results. This may cause duplicate calls for the same query in the same batch.

fix

Set cache: true to enable caching, or handle deduplication manually.

affects: >=1.0.0

gotchaObject query parameters are stringified for cache keys using safe-stable-stringify. Two objects with same properties but different order will be considered equal.

fix

No action needed unless you rely on property order for uniqueness; then use a primitive key.

affects: >=1.0.0

deprecatedThe maxBatchSize option defaults to undefined (unlimited). Setting a low number may cause unexpected splitting of batches.

fix

Leave maxBatchSize undefined for full batching, or set to a positive integer to limit batch size.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: factory.add is not a function

Using a wrong import (e.g., importing default export as if it were a class with add method).

fix

Ensure you import Factory correctly: import { Factory } from 'single-user-cache' or const { Factory } = require('single-user-cache').

Error: Cannot find module 'safe-stable-stringify'

Dependency missing when installing the package in an environment without auto-install of peer dependencies.

fix

Install the missing dependency: npm install safe-stable-stringify

TypeError: context is not an object

Passing a non-object (e.g., string) as context to factory.create.

fix

Pass a plain object as context: factory.create({ requestId: 'abc' })

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

safe-stable-stringifyrequiredUsed to generate cache keys for object query parameters

Agent activity

20 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/mcollina/single-user-cache ↗

packagesingle-user-cache ↗

homepagehttps://github.com/mcollina/single-user-cache#readme ↗