`tier/tier.ts`

(no submodules)

Purpose

Computes the deterministic Tier label for a package given its shortname and the parsed package.json shape. The inference order mirrors scripts/folder-reorg/generate-manifest.ts exactly, so consumers can rely on the library and the script producing identical tier assignments for the same input.

The function is pure and synchronous. It takes no side-effects, so it is safe to call from any tier — including the universal root barrel — even though some of the dep hints it inspects are Node-only.

Features

Six-rung priority cascade — python → r3f → react → browser → server → universal
Exported SERVER_DEP_HINTS set for downstream introspection
Optional extraHints parameter merges user-supplied server-tier dep names with the built-in set
Pure / synchronous — zero I/O, zero allocations on the universal fallback path beyond the merged-hint set

Usage: Basic

import { inferTier } from "@suaveplan/overview";

const tier = inferTier("foo", {
  dependencies: { "node:fs": "*" },
});
// tier === "server"

Usage: Advanced

import { inferTier, SERVER_DEP_HINTS } from "@suaveplan/overview";

const extra = new Set(["custom-native-binding"]);
const tier = inferTier(
  "thing",
  { dependencies: { "custom-native-binding": "*" } },
  extra,
);

// SERVER_DEP_HINTS exposes the built-in set for tooling that wants to
// surface the rule set in a UI without re-declaring it.
console.log([...SERVER_DEP_HINTS]);

The optional third argument is the path for tooling that wants to extend the hint set (e.g. a project-local native-binding registry) without forking the library. The base set is read-only and never mutated.

API Reference

inferTier(short: string, pkg: RawPackageJson, extraHints?: ReadonlySet<string>): Tier
const SERVER_DEP_HINTS: ReadonlySet<string> — eighteen built-in entries spanning node:* modules and known native bindings

Implementation Notes

The function performs at most one shallow Object.keys pass over each of peerDependencies, engines, dependencies, and devDependencies — O(1) work per package.json in practice. The mergeHints helper allocates a new Set only when extraHints carries entries; otherwise it returns the base set unchanged so the common path is allocation-free.

2.4 KiB Raw Blame History

tier/tier.ts