Skip to main content

Taphos

*τάφος - "tomb"

The resting place of utilities*

Taphos is Pithos's "tomb" module: a place where utilities come to rest. Named after the Greek word for "tomb," Taphos serves two main purposes:

  1. A strategic migration guide helping you transition from Lodash utilities to their proper replacements
  2. IDE-integrated deprecation warnings showing the migration path directly in your editor
Progressive migration

Even before the final switch to native, migrating through Taphos already brings concrete benefits: a smaller bundle and better performance compared to Lodash or es-toolkit. Every step is a win.

Why a Tomb?

The metaphor is intentional and meaningful:

Dead Code
When a utility ends up in Taphos, it means the code is dead. There's a better way now: Whether native JavaScript, a Pithos alternative, or simply a different approach. The message is clear: don't use this anymore.

A Ceremony
These utilities served us well. Lodash, Underscore, and similar libraries carried the JavaScript ecosystem for years. Taphos is a way to honor their service while acknowledging it's time to move on. It's a respectful farewell, not an unceremonious deletion.

A Memorial to Visit
Like a memorial, Taphos is a place you can visit to learn. Want to know how to do something in modern JavaScript? Want to understand why a certain pattern is discouraged? Taphos documents these use-cases and points you to the right solution.

The Four Types of Burials​

Not all functions in Taphos are buried for the same reason. Understanding the type of burial helps you know where to migrate.

1. Superseded by Native JavaScript​

These utilities have been replaced by native JavaScript/TypeScript APIs. The native version is now the canonical way. This is similar to what You Don't Need Lodash/Underscore documents.

// Buried in Taphos
import { flatten } from "@pithos/core/taphos/array/flatten";
const flat = flatten([[1, 2], [3, 4]]);

// ✅ Native replacement, see Array.prototype.flat() on MDN
const flat = [[1, 2], [3, 4]].flat();

Migration direction: Taphos → Native JavaScript

2. Native Exists but Violates Pithos Principles​

Some native JavaScript functions exist but go against Pithos's design principles, typically because they mutate data. These are buried to discourage their use in favor of immutable Pithos alternatives.

// ❌ Native sort mutates
const arr = [3, 1, 2];
arr.sort(); // arr is now [1, 2, 3] - mutated!

// ✅ Use Pithos immutable alternative
import { sort } from "@pithos/core/arkhe/array/sort";
const sorted = sort([3, 1, 2]); // Returns new array, original unchanged

Migration direction: Taphos → Arkhe (Pithos immutable alternative)

3. Aliases for Migration Convenience​

Some functions in Taphos aren't truly "dead": they're aliases that redirect to the canonical Pithos function. These exist to help developers coming from other libraries (Lodash, Ramda, etc.) find the right function.

// Alias in Taphos (Lodash naming)
import { castArray } from "@pithos/core/taphos/util/castArray";

// ✅ Canonical Pithos function
import { toArray } from "@pithos/core/arkhe/array/toArray";

// Both do the same thing, but 'toArray' is the canonical name in Pithos

This isn't a real burial, it's a signpost saying "you're looking for X? It's over here now."

Migration direction: Taphos alias → Canonical Pithos function

4. Marked for Future Burial​

Some utilities are still in Arkhe but have a known native replacement that's too recent to use. They're living on borrowed time: once the target ES version allows it, they'll be moved to Taphos.

Think of it as a reserved plot in the cemetery. We know who's going there, just not when.

// Still in Arkhe (targeting ES2020)
import { groupBy } from "@pithos/core/arkhe/collection/groupBy";
const grouped = groupBy(users, (user) => user.role);

// Future native replacement (ES2024) - not yet available for our target
// const grouped = Object.groupBy(users, (user) => user.role);

Status: Arkhe (for now) → Taphos (when ES target allows)

IDE-Guided Migration​

Every function in Taphos is marked @deprecated and includes its migration path directly in the TSDoc. This means your IDE shows you exactly what to use instead, without leaving your editor.

import { at } from "@pithos/core/taphos/array/at";
//       ^^ Your IDE shows: "Deprecated: Use native Array.prototype.at() instead"

When you hover over a Taphos function or see the deprecation warning, the TSDoc tells you:

  • Why it's deprecated (native replacement, Arkhe alternative, etc.)
  • What to use instead
  • How to migrate with code examples
Taphos TSDoc migration hints showing deprecation warnings and replacement suggestions in IDE

This makes migration progressive and frictionless: you can keep using Taphos functions while gradually replacing them, guided by your IDE at each step. They'll stay marked @deprecated as long as you use them, a quiet reminder that a migration is possible.

Related Resources