Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LruCache
✓ import { LruCache } from 'thingies';
✗ const { LruCache } = require('thingies');
Since v2.0.0, the library targets ES2020 modules, primarily designed for ESM environments. CommonJS `require()` will not work directly for named exports.
of
✓ import { of } from 'thingies';
✗ import of from 'thingies';
All public utilities are exposed as named exports. There are no default exports in this library.
codeMutex
✓ import { codeMutex } from 'thingies';
Useful for synchronizing asynchronous operations to prevent race conditions.
TimedQueue
✓ import { TimedQueue } from 'thingies';
✗ import * as thingies from 'thingies'; const queue = new thingies.TimedQueue();
While `import * as thingies` works, direct named imports are preferred for tree-shaking and clarity.
This quickstart demonstrates the usage of `LruCache` for in-memory caching, `of` for robust promise error handling, `codeMutex` for synchronizing concurrent operations, and `TimedQueue` for batching events based on count or time thresholds.
import { LruCache, of, codeMutex, TimedQueue } from 'thingies';
// 1. Using LruCache for efficient data storage
const userCache = new LruCache<string, { id: string; name: string }>({
limit: 100, // Cache up to 100 users
ttl: 60 * 1000, // Items expire after 60 seconds
});
userCache.set('user-1', { id: 'user-1', name: 'Alice' });
console.log('Cached user:', userCache.get('user-1'));
// 2. Safely handling Promise results with `of`
async function fetchData(shouldSucceed: boolean) {
const [data, error] = await of(new Promise<string>((resolve, reject) => {
setTimeout(() => {
if (shouldSucceed) {
resolve('Data fetched successfully');
} else {
reject(new Error('Failed to fetch data'));
}
}, 100);
}));
if (error) {
console.error('Error fetching data:', error.message);
} else {
console.log('Data:', data);
}
}
fetchData(true); // Should log data
fetchData(false); // Should log error
// 3. Using codeMutex for synchronized execution
const mutex = codeMutex();
let sharedResource = 0;
async function incrementResource(id: number) {
await mutex(async () => {
const current = sharedResource;
await new Promise(resolve => setTimeout(resolve, Math.random() * 50)); // Simulate work
sharedResource = current + 1;
console.log(`Worker ${id}: sharedResource is now ${sharedResource}`);
});
}
Promise.all([incrementResource(1), incrementResource(2), incrementResource(3)]);
// 4. Batching operations with TimedQueue
const eventQueue = new TimedQueue<string>({
limit: 3, // Flush after 3 items
timeout: 100, // Or flush after 100ms
flush: async (items) => {
console.log(`Flushing ${items.length} events: ${items.join(', ')}`);
// In a real app, this would send to an external service or database
},
});
eventQueue.push('event-A');
eventQueue.push('event-B');
eventQueue.push('event-C'); // This push should trigger a flush immediately
eventQueue.push('event-D');
eventQueue.push('event-E');
// Wait for timeout to flush remaining items
setTimeout(() => eventQueue.flush(), 200);
Errors
Common errors & fixes
ReferenceError: require is not defined in ES module scope
Attempting to use `require()` to import `thingies` after version 2.0.0, which switched to ES modules.
fixChange `const { Symbol } = require('thingies');` to `import { Symbol } from 'thingies';` and ensure your environment supports ES modules (e.g., `"type": "module"` in `package.json` for Node.js). TypeError: Class extends value undefined is not a constructor or null
This error often indicates a problem with `tslib` not being found or an incompatible version being used, especially when TypeScript features like class extension or decorators are involved.
fixVerify that `tslib` is installed in your project (`npm list tslib`) and that its version is compatible with your TypeScript compiler and runtime environment. Try `npm install tslib@^2`.
TypeError: (0 , thingies_1.LruCache) is not a constructor
This typically occurs in transpiled JavaScript when an ES module's named export (like `LruCache`) is incorrectly handled during CommonJS interop, often due to mismatched module systems or incorrect bundler configuration.
fixEnsure your build system (Webpack, Rollup, TypeScript compiler) is correctly configured for ES module output and consumption, especially when targeting older environments or using CommonJS. Prefer direct `import { LruCache } from 'thingies';` and verify `tsconfig.json` module settings. Audit
Dependencies
tslibrequiredRuntime helper library for TypeScript, often required by TypeScript builds for features like decorators and async/await.