@superutils

@superutils is a collection of small, battle-tested TypeScript utilities for solving recurring production problems without hidden abstractions. Evolved from patterns proven over a decade in real-world systems, the library includes both framework-agnostic utilities and packages tailored for ecosystems like React. Each tool is designed to be modular, explicit, and maintainable, reflecting a preference for simple and reliable building blocks.

Table of Contents

• Why @superutils exists
• Design philosophy
• Non-goals
• Packages
• Getting Started
  • NPM
  • CDN/Browser
• Contribute
• License

Why @superutils exists

Over the years, I kept encountering the same recurring problems across different teams and products: managing async flows cleanly, reducing repeated boilerplate, and enforcing correctness without hiding control flow. In production systems, including my work at Totem Accounting, many of these solutions were built ad hoc and slowly drifted across codebases, which I later consolidated into a single repository. That repository, however, still carried project-specific assumptions and needed further modularization and cleaner abstractions to become truly reusable across different systems.

@superutils is a distillation of the patterns that consistently held up. It focuses on small, explicit, production-ready utilities that prioritize clarity, predictable behavior, and long-term maintainability over clever abstractions.

Design philosophy

• Utilities should be small enough to understand in one sitting
• APIs should be explicit and unsurprising
• Systems should be fault-tolerant, with failure remaining observable when needed
• Defaults should be conservative and opt-in
• Types should aid correctness without obscuring runtime behavior

Non-goals

• Not a framework or application architecture
• Not a monolithic utility bundle
• No hidden global state or implicit side effects
• No runtime magic, patching, or environment mutation
• No attempt to abstract away fundamental complexity

Packages

This monorepo contains the following packages. Each is independently versioned and published to NPM.

NPM Package	Description	Test Coverage	Docs
@superutils/core	A collection of lightweight, dependency-free utility functions and types. Why: prevents copy-pasted helpers from drifting across codebases.	💘 100%	View
@superutils/fetch	A lightweight fetch wrapper for browsers and Node.js, designed to simplify data fetching and reduce boilerplate. Why: address recurring production issues around retries, cancellation, and request lifecycles in a consistent, observable way.	💘 100%	View
@superutils/promise	An extended Promise with additional features such as status tracking, deferred/throttled execution, timeout and retry mechanism. Why: provide shared async primitives used across higher-level utilities.	💘 100%	View
@superutils/react	A collection of React hooks and components for common UI patterns and state management.	📝 Planned	View
@superutils/rx	A set of small, focused utilities for working with RxJS observables and subjects. Why: avoid re-implementing common RxJS subject and lifecycle patterns across codebases	📝 Planned	View

Getting Started

NPM

All packages are scoped under @superutils and will be available on the NPM registry. You can install any package using your preferred package manager (e.g., npm, yarn, pnpm, bun, etc.).

# Installing the @superutils/fetch package
npm install @superutils/fetch

Once installed, you can import the utilities directly into your project.

import fetch from '@superutils/fetch'

fetch
	.get('[DUMMYJSON-DOT-COM]/products', {
		interceptors: {
			// transform result
			result: products =>
				products.map(p => ({
					...p,
					updated: new Date().toISOString(),
				})),
		},
		timeout: 5000,
	})
	.then(console.log)

CDN / Browser

If you are not using a bundler, you can include the minified browser build directly:

<script src="https://unpkg.com/@superutils/fetch@latest/dist/browser/index.min.js"></script>

OR,

<script src="https://cdn.jsdelivr.net/npm/@superutils/fetch@latest/dist/browser/index.min.js"></script>

This exposes a global superutils object containing the exports of any loaded packages:

superutils.core // All exports from `@superutils/core`
superutils.fetch // Default export (function) from `@superutils/fetch` + named exports
superutils.PromisE // Default export (class) from `@superutils/promise` + named exports

For more details please read the API reference for respective packages.

Contribute

For contribution guidelines and development standards used in this project, see CONTRIBUTING.md.

License

This project is licensed under the MIT License. See the LICENSE file in each package for more details.