{"id":12332,"library":"utilium","title":"Utilium: TypeScript Utilities","description":"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.","status":"active","version":"3.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/james-pre/utilium","tags":["javascript","typescript"],"install":[{"cmd":"npm install utilium","lang":"bash","label":"npm"},{"cmd":"yarn add utilium","lang":"bash","label":"yarn"},{"cmd":"pnpm add utilium","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Utilium is designed for modern JavaScript environments and primarily uses ESM. CommonJS `require` is not officially supported and may lead to issues.","wrong":"const { List } = require('utilium')","symbol":"List","correct":"import { List } from 'utilium'"},{"note":"Introduced in v3.1.0, this function helps parse command-line like arguments.","symbol":"splitIntoArgs","correct":"import { splitIntoArgs } from 'utilium'"},{"note":"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.","symbol":"@memoize","correct":"import { memoize } from 'utilium'; class MyClass { @memoize myMethod() { ... } }"},{"note":"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`.","symbol":"requests","correct":"import { requests } from 'utilium'"}],"quickstart":{"code":"import { List, splitIntoArgs, requests } from 'utilium';\n\n// Demonstrate the List class\nconst myList = new List([1, 2, 2, 3]);\nconsole.log(`Initial List: ${myList.toArray()}`); // Output: Initial List: 1,2,3\nmyList.add(4);\nmyList.remove(2);\nconsole.log(`Modified List: ${myList.toArray()}`); // Output: Modified List: 1,3,4\n\n// Demonstrate splitIntoArgs\nconst args = splitIntoArgs('command --flag value -x \"quoted arg\"');\nconsole.log('Parsed arguments:', args); // Output: Parsed arguments: [ 'command', '--flag', 'value', '-x', 'quoted arg' ]\n\n// Demonstrate usage of nested exports (requests namespace)\nconst issue: requests.Issue = {\n  code: 'FETCH_ERROR',\n  message: 'Network request failed'\n};\nconsole.log('Request Issue:', issue);\n\n// You can also demonstrate compile-time types, but they don't produce runtime output directly.\n// Example of a compile-time type (cannot be run directly, but shows intent):\n// import type { Add } from 'utilium/types';\n// type Sum = Add<5, 3>; // Sum will be 8 at compile-time\n","lang":"typescript","description":"This quickstart demonstrates the `List` class, `splitIntoArgs` function, and access to namespaced utilities like `requests.Issue`."},"warnings":[{"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 = ...`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove the `.js` extension from subpath imports. Change `import { example } from 'utilium/sub.js'` to `import { example } from 'utilium/sub'`.","message":"Since v3.0.0, direct subpath imports no longer require the `.js` file extension. Importing `utilium/sub.js` will fail.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.8.2 <2.8.8"},{"fix":"Upgrade your Node.js runtime to version 22.0.0 or newer.","message":"Utilium requires Node.js version 22.0.0 or higher. Running in older Node.js environments will lead to errors.","severity":"gotcha","affected_versions":"<22.0.0 (Node.js)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Remove the `.js` extension from the import path: `import { example } from 'utilium/sub'`.","cause":"Attempting to import a subpath with a `.js` extension after version 3.0.0.","error":"Cannot find module 'utilium/sub.js'"},{"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'`.","cause":"Attempting to use CommonJS `require` for ESM-only exports. Utilium is primarily an ESM library.","error":"TypeError: (0 , utilium_1.List) is not a constructor"},{"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 = { ... };`.","cause":"Accessing a top-level export that was removed or moved under a namespace in v3.0.0.","error":"Property 'RequestError' does not exist on type 'typeof import(\"utilium\")'"}],"ecosystem":"npm"}