Get Started

Everything you need to know about Pithos in 5 minutes.

Pithos is a TypeScript utilities library with zero dependencies, designed for modern web development. One package gives you data manipulation, schema validation, and functional error handling: all tree-shakable and fully typed.

Installation

npm

npm install @pithos/core

pnpm

pnpm install @pithos/core

yarn

yarn add @pithos/core

bun

bun add @pithos/core

That's it. Zero dependencies means zero headaches.

---

What's in the box?

Pithos is a complete utilities ecosystem. One package, five modules:

Module	What it does
Arkhe	Data manipulation (arrays, objects, strings, functions, ...)
Kanon	Schema validation with JIT support
Zygos	Functional error handling (Result, Option, Either, Task)
Sphalma	Typed error factories with hex codes
Taphos	Migration guide & deprecated utilities with IDE hints

---

How to import

Pithos uses granular entry points for optimal tree-shaking. Import each function directly from its module path, and your bundler will only include the code you actually use:

// Array utilities
import { chunk } from "pithos/arkhe/array/chunk";

// Validation
import { object, string, number, optional } from "pithos/kanon";

// Result pattern
import { ok, err } from "pithos/zygos/result/result";

---

Quick examples

Data manipulation

Arkhe utilities follow a consistent pattern: they take the data as the first argument and return a new value without mutating the original.

This makes them safe to use in any context, from React state updates to server-side processing:

import { chunk } from "pithos/arkhe/array/chunk";
import { get } from "pithos/arkhe/object/get";

// Split array into chunks
chunk([1, 2, 3, 4, 5], 2);
// → [[1, 2], [3, 4], [5]]

// Safe nested access
const user = { profile: { address: { city: "Paris" } } };
get(user, "profile.address.city", "Unknown");
// → "Paris"

Validation

Kanon schemas compose together to describe complex data structures. The parse function returns a discriminated union, so TypeScript narrows the type automatically in each branch.
Already using Zod? The asZod wrapper provides a compatible API, so you can migrate incrementally and benefit from Kanon's full tree-shaking:

import { object, string, number, optional, parse } from "pithos/kanon";
import { asZod } from "pithos/kanon/helpers/as-zod";

const userSchema = object({
  name: string(),
  email: string().email(),
  age: optional(number()),
});

// Kanon API
const result = parse(userSchema, data);
if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error);
}

// Zod-like API
const zSchema = asZod(userSchema);
const zodResult = zSchema.safeParse(data);
if (zodResult.success) {
  console.log(zodResult.data);
} else {
  console.error(zodResult.error.issues);
}

Error handling

ResultAsync wraps Promise-based operations in the Result pattern.

Instead of try/catch, you get a typed value that forces you to handle both success and failure paths:

import { ResultAsync } from "pithos/zygos/result/result-async";

const safeFetch = ResultAsync.fromThrowable(
  fetch,
  (error) => `Network error: ${error}`
);

const result = await safeFetch("/api/users/1");

if (result.isOk()) {
  console.log(result.value);
} else {
  console.error(result.error); // No try/catch needed
}

---

Why developers love it

Full TypeScript inference. Type it once, infer it everywhere. No manual generics, no any leaks.

Zero dependencies. Complete supply chain security. What you install is what you get.

Tree-shakable by design. Import only what you use. Your bundle stays small.

Modern JavaScript. ES2020+, no legacy baggage.

Why your users benefit

~7× faster on average. Your app feels snappier. Users wait less, interactions respond faster.

~9× smaller bundles on average. Pages load fast, even on slow connections or low-end devices.

Battle-tested reliability. Things just work. No surprise crashes or edge-case glitches.

No silent errors. Bugs are caught before they ship, so your users never hit unexplainable behavior.

---

What's next?

Looking for use cases?

Explore practical examples and find the right utility for your needs in the Use Cases Explorer.

• About Pithos - The story and philosophy behind the project
• Installation guide - Advanced setup and configuration
• Practical Example - Build something real with Pithos