@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: 'high', 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,
//   preferServerRendering: false,
//   disable3dEffects: false,
//   limitVideoQuality: false,
//   useSystemFonts: false,
//   disablePrefetch: false,
// }

Rendering hints are derived from tiers and transient signals:

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: { highUpperBound: 10 },
  gpu: { highEndPattern: /\bRTX\b|\bGTX\b/i },
});

Validate thresholds

Thresholds are validated automatically by createDeviceRouter(). For standalone usage with classify(), call validateThresholds() explicitly:

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

validateThresholds({
  cpu: { lowUpperBound: 4, midUpperBound: 8 },
}); // OK

validateThresholds({
  cpu: { lowUpperBound: 10, midUpperBound: 2 },
}); // throws Error

Validate incoming signals

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

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

Tier classification

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
• validateThresholds(thresholds) — Validate custom thresholds (called automatically by middleware)
• isValidSignals(body) — Type guard for RawSignals
• isBotSignals(signals) — Detect bot/crawler/headless browser probe submissions
• classifyFromHeaders(headers) — Classify from UA/Client Hints headers
• resolveFallback(fallback) — Resolve a fallback profile preset or custom tiers
• extractErrorMessage(err) — Extract a string message from an unknown error value

Constants

• CONSERVATIVE_TIERS — Low-end device tier preset
• OPTIMISTIC_TIERS — High-end device tier preset
• ACCEPT_CH_VALUE — Accept-CH header value for requesting Client Hints

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 + source
• ProfileSource — 'probe' | 'headers' | 'fallback'
• FallbackProfile — 'conservative' | 'optimistic' | DeviceTiers
• TierThresholds — Custom threshold configuration
• CpuTier, MemoryTier, ConnectionTier, GpuTier — Individual tier types

License

MIT