Umsizi

The missing TypeScript standard library.

Umsizi (pronounced oom-see-zee) is a modern, zero-dependency utility library built from the ground up for TypeScript applications. The name comes from the Zulu word for "helper" or "assistant"—which is exactly what this library is designed to be.

It provides small, focused utilities that preserve types, eliminate repetitive code, and replace the disorganized utils/ folder every project eventually creates.

import { identity } from "umsizi";

const user = {
	id: "1",
	name: "Jack",
};

const result = identity(user);
// inferred as:
// {
//   id: string;
//   name: string;
// }

Why Umsizi

Most TypeScript projects slowly accumulate a standard set of custom helpers:

src/
 └─ utils/
     ├─ arrays.ts
     ├─ objects.ts
     ├─ promises.ts
     └─ guards.ts

These copy-pasted snippets usually become undocumented, inconsistently typed, and completely untested. Umsizi replaces that folder with a single, production-ready, and highly optimized package.

Core Principles

• TypeScript-First: Built around strict type inference. Types flow naturally through every utility so you never have to manually cast with as.
• Composition Over Configuration: Every function does exactly one thing cleanly, favoring simple composition over complex, bloated configuration objects.
• Zero Dependencies: No runtime dependencies means smaller installs, fewer security vulnerabilities, and predictable behavior.
• Tree-Shakable: Only ship what you use. Unused utilities will never affect your production bundle size.
• Immutable by Default: Utilities avoid mutating your existing data structures.

Installation

Install via your package manager of choice:

# npm
npm install umsizi

# pnpm
pnpm add umsizi

# yarn
yarn add umsizi

# bun
bun add umsizi

Package Structure

Umsizi is split into focused entry points:

import { identity } from "umsizi";
import { isRenderFunction } from "umsizi/react";
import { normalizePathname } from "umsizi/next";
import { hasFileExtension } from "umsizi/node";

Current structure:

src/
  core/
  react/
  next/
  node/

• umsizi: framework-agnostic core utilities
• umsizi/react: React-oriented helpers
• umsizi/next: Next.js-oriented helpers
• umsizi/node: Node-oriented helpers

API Reference

Core Utilities

Full signatures, edge cases, and runnable examples for every utility live in docs/; this section is a quick-reference index.

Key/Value Iteration — identity returns a value unchanged · typedKeys typed Object.keys() · typedEntries typed Object.entries() · typedFromEntries typed Object.fromEntries() · mapValues maps values, keeps keys · mapKeys maps keys, keeps values

Selection & Filtering — pick keeps selected keys · omit drops selected keys · filterValues filters by value · filterKeys filters by key · partitionObject splits into matching/non-matching · renameKeys renames selected keys · invertObject swaps keys and values · compactObject drops null/undefined values

Type Checking — isPlainObject guards plain objects · isEmpty checks for no own properties · hasOwn typed Object.hasOwn() · hasKeys checks required keys exist · requireKeys returns object or throws · assertKeys asserts required keys exist

Nested Paths — path parses dot/bracket notation · get reads a nested value · set immutably writes a nested value · hasPath checks a nested path exists · flattenObject flattens to path-notation keys · unflattenObject reverses flattenObject()

Defaults & Merging — defaults fills missing values, one level deep · mergeDefaults recursively fills missing values · withDefaults curries mergeDefaults() · deepMerge recursively merges with the source winning

Deep Operations — deepClone recursively clones objects/arrays · deepEqual structural equality check · diffObject computes added/removed/changed keys

Schema Validation — validateObject validates against field validators · parseObject validates or throws

Collections — groupByKey groups array items by key · indexByKey indexes array items by key · matchByKey matches items across two arrays by key

React Utilities (umsizi/react)

isRenderFunction

Small guard for values that should be callable in render-oriented code paths.

import { isRenderFunction } from "umsizi/react";

const value: unknown = () => "ready";

if (isRenderFunction(value)) {
	value();
}

Next.js Utilities (umsizi/next)

normalizePathname

Normalizes path-like strings by ensuring a leading slash, collapsing duplicate slashes, and preserving root.

import { normalizePathname } from "umsizi/next";

normalizePathname("dashboard");
// "/dashboard"

normalizePathname("//dashboard///settings");
// "/dashboard/settings"

Node.js Utilities (umsizi/node)

hasFileExtension

Checks whether a file path ends with a specific extension.

import { hasFileExtension } from "umsizi/node";

hasFileExtension("src/index.ts", ".ts");
// true

hasFileExtension("package.json", "json");
// true

Compatibility

• ESM-only. Umsizi ships only as ECMAScript modules (no CommonJS build). require("umsizi") will not work; use import. If your project is on CommonJS, you'll need a dynamic import() or a bundler that handles ESM dependencies.
• Node.js 20+. Enforced via engines.node in package.json.
• Browsers: the code targets ES2022 and has no Node-specific APIs in umsizi (core), umsizi/react, and umsizi/next; umsizi/node is Node-only by design. Bundle through your usual toolchain (Vite, Webpack, etc.) — there's no separate browser build.

Error Handling Philosophy

Umsizi utilities trust their inputs to match their TypeScript signatures. They do not perform runtime validation, and they do not throw — invalid input (e.g. calling a Node-typed function with a non-string) produces an unspecified but non-throwing result rather than an exception.

If you're handling untrusted input (user input, network responses, unknown/any values), validate or narrow it before passing it into Umsizi. This keeps the utilities small, predictable, and fast, matching their role as thin building blocks rather than a validation layer.

Versioning & Stability

Umsizi follows semantic versioning. While the package is 0.x:

• Minor versions (0.x.0) may include breaking changes to the public API.
• Patch versions (0.0.x) are bug fixes only.
• Once the API stabilizes, 1.0.0 will commit to standard semver guarantees (breaking changes only on major versions).

Releases are managed via Changesets and npm trusted publishing from GitHub Actions; see the generated CHANGELOG.md for version history.

Examples

See examples/ for runnable, slightly more realistic usage of each utility beyond the snippets below.

Current Status

Umsizi is still in early development. The package structure is in place, the initial utilities are implemented, and the public API is intentionally small.

New helpers should only be added when they meet the project standards for:

• type safety
• runtime correctness
• API clarity
• zero-dependency design

How Umsizi Compares

• vs Lodash: Lodash was built for an era before modern JavaScript and TypeScript existed. Umsizi embraces modern JS features and prioritizes zero-overhead type inference.
• vs Radash: While Radash is excellent, Umsizi hones in purely on application development patterns and strict, seamless type inference.
• vs Remeda: Remeda heavily emphasizes functional programming paradigms like data-last currying. Umsizi targets straightforward, standard-library-style code for everyday projects.

Contributing

See CONTRIBUTING.md.

If you want to introduce a helper, ensure it meets the baseline:

1. It solves a highly recurring, real-world application problem.
2. It features bulletproof TypeScript type safety.
3. It includes comprehensive runtime and type-level tests.
4. It remains entirely dependency-free.

Security

See SECURITY.md for the vulnerability reporting policy.

License

MIT