@device-router/types

Type definitions, device classification, and rendering hint derivation for DeviceRouter.

Installation

pnpm add @device-router/types

Usage

Classify device signals into tiers

import { classify } from '@device-router/types';

const tiers = classify({
  hardwareConcurrency: 8,
  deviceMemory: 8,
  connection: { effectiveType: '4g', downlink: 50 },
  gpuRenderer: 'ANGLE (Apple, Apple M2 Pro, OpenGL 4.1)',
});
// { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' }

Derive rendering hints

import { classify, deriveHints } from '@device-router/types';

const tiers = classify(signals);
const hints = deriveHints(tiers, signals);
// {
//   deferHeavyComponents: false,
//   serveMinimalCSS: false,
//   reduceAnimations: false,
//   useImagePlaceholders: false,
//   disableAutoplay: false,
//   preferServerRendering: false,
//   disable3dEffects: false,
// }

Rendering hints are derived from tiers and transient signals:

Hint	When `true`
`deferHeavyComponents`	Low-end device, slow connection, or low battery
`serveMinimalCSS`	Low-end device
`reduceAnimations`	Low-end device, prefers reduced motion, or low battery
`useImagePlaceholders`	Slow connection (2G/3G)
`disableAutoplay`	Low-end device, slow connection, or low battery
`preferServerRendering`	Low-end device
`disable3dEffects`	No GPU or software renderer

The battery signal bypasses tier classification — it's transient state, not a capability. When unplugged and below 15% charge, power-sensitive hints are forced on.

Custom thresholds

Override default tier boundaries:

import { classify } from '@device-router/types';

const tiers = classify(signals, {
  cpu: { lowUpperBound: 4, midUpperBound: 8 },
  memory: { midUpperBound: 8 },
  connection: { downlink4gUpperBound: 10 },
  gpu: { highEndPattern: /\bRTX\b|\bGTX\b/i },
});

Validate incoming signals

import { isValidSignals } from '@device-router/types';

if (isValidSignals(requestBody)) {
  // requestBody is typed as RawSignals
}

Tier classification

Dimension	Low	Mid	High/Fast
CPU	1-2 cores	3-4 cores	5+ cores
Memory	<=2 GB	2-4 GB	>4 GB
Connection	2G	3G / slow 4G	Fast 4G+ (>=5 Mbps)
GPU	Software renderer	Mid-range	RTX, RX 5000+, Apple M-series

Exports

Functions

classify(signals, thresholds?) — Classify raw signals into DeviceTiers
classifyCpu(hardwareConcurrency?, thresholds?) — CPU tier
classifyMemory(deviceMemory?, thresholds?) — Memory tier
classifyConnection(effectiveType?, downlink?, thresholds?) — Connection tier
classifyGpu(renderer?, thresholds?) — GPU tier
deriveHints(tiers, signals?) — Derive RenderingHints from tiers and signals
isValidSignals(body) — Type guard for RawSignals

Types

RawSignals — Browser-collected device signals
DeviceTiers — Classified capability tiers (cpu, memory, connection, gpu)
RenderingHints — Boolean rendering decisions
DeviceProfile — Full profile with schema version, session token, timestamps, and signals
ClassifiedProfile — Profile + tiers + hints
TierThresholds — Custom threshold configuration
CpuTier, MemoryTier, ConnectionTier, GpuTier — Individual tier types

License

MIT