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.
List
✓ import { List } from 'utilium'
✗ const { List } = require('utilium')
Utilium is designed for modern JavaScript environments and primarily uses ESM. CommonJS `require` is not officially supported and may lead to issues.
splitIntoArgs
✓ import { splitIntoArgs } from 'utilium'
Introduced in v3.1.0, this function helps parse command-line like arguments.
@memoize
✓ import { memoize } from 'utilium'; class MyClass { @memoize myMethod() { ... } }
The `@memoize` decorator is a runtime utility for caching method results. Ensure you are using a recent v2.8.x or v3.x version for stability due to past bug fixes.
requests
✓ import { requests } from 'utilium'
Since v3.0.0, several request-related utilities like `Issue` and `Options` are nested under the `requests` namespace, replacing old top-level exports like `RequestError` and `RequestOptions`.
This quickstart demonstrates the `List` class, `splitIntoArgs` function, and access to namespaced utilities like `requests.Issue`.
import { List, splitIntoArgs, requests } from 'utilium';
// Demonstrate the List class
const myList = new List([1, 2, 2, 3]);
console.log(`Initial List: ${myList.toArray()}`); // Output: Initial List: 1,2,3
myList.add(4);
myList.remove(2);
console.log(`Modified List: ${myList.toArray()}`); // Output: Modified List: 1,3,4
// Demonstrate splitIntoArgs
const args = splitIntoArgs('command --flag value -x "quoted arg"');
console.log('Parsed arguments:', args); // Output: Parsed arguments: [ 'command', '--flag', 'value', '-x', 'quoted arg' ]
// Demonstrate usage of nested exports (requests namespace)
const issue: requests.Issue = {
code: 'FETCH_ERROR',
message: 'Network request failed'
};
console.log('Request Issue:', issue);
// You can also demonstrate compile-time types, but they don't produce runtime output directly.
// Example of a compile-time type (cannot be run directly, but shows intent):
// import type { Add } from 'utilium/types';
// type Sum = Add<5, 3>; // Sum will be 8 at compile-time
Debug
Known issues
breakingVersion 3.0.0 introduced significant breaking changes by removing numerous top-level exports and consolidating them under namespaces. For instance, `ResourceCache`, `RequestError`, and `Increment` were removed, with their functionalities moved to `cache.Resource`, `requests.Issue`, and `Add<..., 1>` respectively.fixReview the v3.0.0 release notes and update import paths and symbol names. For example, change `import { RequestError } from 'utilium'` to `import { requests } from 'utilium'; const error: requests.Issue = ...`. affects: >=3.0.0
breakingSince v3.0.0, direct subpath imports no longer require the `.js` file extension. Importing `utilium/sub.js` will fail.fixRemove the `.js` extension from subpath imports. Change `import { example } from 'utilium/sub.js'` to `import { example } from 'utilium/sub'`. affects: >=3.0.0
gotchaThe `@memoize` decorator had several stability fixes between versions 2.8.2 and 2.8.8. Older versions might exhibit incorrect caching behavior, particularly with auto-accessors.fixEnsure you are using `utilium` version 2.8.8 or later (including any 3.x release) to benefit from the `@memoize` decorator's stability improvements.
affects: >=2.8.2 <2.8.8
gotchaUtilium requires Node.js version 22.0.0 or higher. Running in older Node.js environments will lead to errors.fixUpgrade your Node.js runtime to version 22.0.0 or newer.
affects: <22.0.0 (Node.js)
Errors
Common errors & fixes
Cannot find module 'utilium/sub.js'
Attempting to import a subpath with a `.js` extension after version 3.0.0.
fixRemove the `.js` extension from the import path: `import { example } from 'utilium/sub'`. TypeError: (0 , utilium_1.List) is not a constructor
Attempting to use CommonJS `require` for ESM-only exports. Utilium is primarily an ESM library.
fixMigrate your project to use ES Modules (ESM) and `import` statements, or configure your bundler/TypeScript compiler to correctly handle ESM interoperability. E.g., `import { List } from 'utilium'`. Property 'RequestError' does not exist on type 'typeof import("utilium")'
Accessing a top-level export that was removed or moved under a namespace in v3.0.0.
fixRefer to the v3.0.0 release notes. `RequestError` was replaced by `requests.Issue`. Update your code to `import { requests } from 'utilium'; const error: requests.Issue = { ... };`. Audit
Dependencies
No dependency data recorded yet.