Thingies: TypeScript Utility Library

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` to import `thingies` after version 2.0.0, which switched to ES modules.
  fix Change `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

  cause 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.
  fix Verify 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

  cause 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.
  fix Ensure 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.

Warnings

• breaking Version 2.0.0 introduced a breaking change by targeting `es2020` modules exclusively, meaning CommonJS environments will require additional transpilation or specific Node.js `--experimental-modules` flags for direct usage.
  Fix: Ensure your project is configured for ES modules, or use a bundler/transpiler like Webpack or Rollup to convert the library to CommonJS if strictly necessary. For Node.js, ensure your `package.json` has `"type": "module"` or use `.mjs` files.
• gotcha The library declares `tslib` as a peer dependency. While npm/yarn often resolve peer dependencies automatically, an incompatible or missing `tslib` version can lead to runtime errors, especially with TypeScript features like decorators or async/await.
  Fix: Explicitly install `tslib` in your project with a version compatible with your TypeScript setup (e.g., `npm install tslib@^2`).
• gotcha Utilities like `codeMutex` and the `@mutex` decorator create mutexes that are scoped to the specific instance or function call. They do not provide global synchronization across different instances or processes.
  Fix: When using `codeMutex` or `@mutex`, ensure you are aware of the scope of synchronization. If global process-wide or distributed locking is needed, consider external solutions like Redis or a database-based lock.

Install

• npm install thingies npm
• yarn add thingies yarn
• pnpm add thingies pnpm

Imports

• LruCache
  wrong:

  const { LruCache } = require('thingies');

  correct:

  import { LruCache } from '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
  wrong:

  import of from 'thingies';

  correct:

  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
  wrong:

  import * as thingies from 'thingies'; const queue = new thingies.TimedQueue();

  correct:

  import { TimedQueue } from 'thingies';

  While `import * as thingies` works, direct named imports are preferred for tree-shaking and clarity.

Quickstart

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);