🏺 Pithos - Utilities Ecosystem

Open the box to unleash the power

All-in-one utilities ecosystem for modern web development. Zero dependencies. 100% TypeScript. Modules designed to work together, more than the sum of their parts.

✨ Key Features

• 🛡️ Production-Ready - 100% test coverage, 100% mutation score, integration demos
• 🔄 Interchangeable APIs - 100% compatible with Neverthrow and fp-ts
• ⚡️ Ultra-Performance - High-speed execution with perfect tree-shaking
• 🏛️ Type it once, infer it everywhere - Full TypeScript inference, no manual generics, no any leaks

🚀 Quick Start

pnpm install @pithos/core

import { ensure } from "@pithos/core/bridges/ensure";
import { string, object, optional, coerceDate } from "@pithos/core/kanon";

// Kanon validates, Zygos wraps - one function, two modules
const userSchema = object({
  name: string(),
  email: string(),
  birthdate: optional(coerceDate()),
});

const result = ensure(userSchema, formData);

if (result.isOk()) {
  save(result.value); // fully typed, validated, coerced
} else {
  showError(result.error); // validation error as string
}

// Or chain with map/mapErr - it's a full Zygos Result
ensure(userSchema, formData)
  .map(user => ({ ...user, name: user.name.trim() }))
  .mapErr(error => `Validation failed: ${error}`);

No manual try/catch, no .safeParse() + if (!result.success) boilerplate. That's the point of having an ecosystem.

📦 Modules

Module	Role	Alternative to
Arkhe (ἀρχή - origin)	Core utilities & data manipulation	Lodash, Underscore, Ramda
Kanon (κανών - rule)	Schema validation	Zod, Yup, Joi
Zygos (ζυγός - balance)	Result/Either/Option patterns	Neverthrow, fp-ts
Sphalma (σφάλμα - error)	Typed error factories	-
Taphos (τάφος - tomb)	Deprecated utils with migration paths	"You Don't Need Lodash"

All modules are stable and production-ready with 100% test coverage.

Like Pandora's pithos that contained both problems and solutions, this ecosystem tackles common development pain points while providing the tools you need. By the way, Pandora's "box" was actually a large jar - pithos in Greek 😉

🌳 Tree Shaking

Direct imports for optimal bundle size:

// ✅ Only what you use
import { chunk } from "@pithos/core/arkhe/array/chunk";
import { debounce } from "@pithos/core/arkhe/function/debounce";

Modules with cohesive APIs (Kanon, Zygos, Sphalma) also expose barrels:

// ✅ Also fine - negligible overhead with modern bundlers
import { string, object, optional } from "@pithos/core/kanon";

🔧 Development

pnpm run dev                # Build in watch mode
pnpm cli                    # Interactive CLI for tests, benchmarks, docs, and more

📖 Documentation

Full documentation, use cases, benchmarks, and migration guides at pithos.dev

🤝 Contributing

Contributions welcome! See the contribution guide for setup and guidelines.

📝 License

MIT