Utilium: TypeScript Utilities

3.1.1 · active · verified Sun Apr 19

Utilium is a comprehensive TypeScript utility library offering a diverse set of functionalities for both compile-time and runtime operations. The current stable version is 3.1.1, with recent releases indicating active development, typically involving feature additions or minor bug fixes within patch versions, and significant refactorings in major versions like 3.0.0. Key differentiators include advanced compile-time mathematical types, utilities for HTTP range requests using `fetch`, robust `Buffer` extension capabilities, and convenience functions for strings and objects. It also features a unique `List` class that merges array and `Set` functionalities, `JSONFileMap` for file system interactions, and specialized tools for Xterm.js shell handling. The library targets modern Node.js environments, requiring Node.js >=22.0.0, and ships with full TypeScript support.

Common errors

```
Cannot find module 'utilium/sub.js'
```
cause Attempting to import a subpath with a `.js` extension after version 3.0.0.

fix Remove the `.js` extension from the import path: `import { example } from 'utilium/sub'`.
```
TypeError: (0 , utilium_1.List) is not a constructor
```
cause Attempting to use CommonJS `require` for ESM-only exports. Utilium is primarily an ESM library.

fix Migrate 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")'
```
cause Accessing a top-level export that was removed or moved under a namespace in v3.0.0.

fix Refer 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 = { ... };`.

Warnings

breaking Version 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.
Fix: Review 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 = ...`.
breaking Since v3.0.0, direct subpath imports no longer require the `.js` file extension. Importing `utilium/sub.js` will fail.
Fix: Remove the `.js` extension from subpath imports. Change `import { example } from 'utilium/sub.js'` to `import { example } from 'utilium/sub'`.
gotcha The `@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.
Fix: Ensure you are using `utilium` version 2.8.8 or later (including any 3.x release) to benefit from the `@memoize` decorator's stability improvements.
gotcha Utilium requires Node.js version 22.0.0 or higher. Running in older Node.js environments will lead to errors.
Fix: Upgrade your Node.js runtime to version 22.0.0 or newer.

Install

npm install utilium npm
yarn add utilium yarn
pnpm add utilium pnpm

Imports

List
wrong:
```
const { List } = require('utilium')
```
correct:
```
import { List } from '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`.

Quickstart

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

view raw JSON →