Bot Classification with Legacy Regex Fallback

Build a small module that reports whether a user agent is a bot and labels which detection engine was used. It must rely on the dependency's automatic downgrade to a naive detector when advanced regex features (such as lookbehind) are unavailable, rather than reimplementing bot matching yourself.

Capabilities

Full detection path

• With default settings, returns { isBot: true, engine: "full" } for a crawler-style user agent such as "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)". @test
• With default settings, returns { isBot: false, engine: "full" } for a modern browser user agent such as "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36". @test

Automatic fallback path

• When advanced regex features are unavailable (simulate by passing { forceLegacy: true }), the crawler user agent still yields { isBot: true, engine: "fallback" }, using the dependency's built-in downgrade instead of custom regex logic. @test
• In fallback mode, null, undefined, empty, or a real browser user agent return { isBot: false, engine: "fallback" } without throwing. @test

Implementation

@generates

API

export interface ClassifyOptions {
  forceLegacy?: boolean;
}

export interface ClassificationResult {
  isBot: boolean;
  engine: "full" | "fallback";
}

export function classifyUserAgent(
  userAgent?: string | null,
  options?: ClassifyOptions
): ClassificationResult;

export function summarizeUserAgents(
  userAgents: Array<string | null | undefined>,
  options?: ClassifyOptions
): {
  total: number;
  bots: number;
  engine: "full" | "fallback";
};

Both exports should share the same detection path: default behavior uses the compiled pattern and reports engine: "full", while forceLegacy: true (or any automatic downgrade when advanced regex is missing) must lean on the dependency's internal fallback and surface engine: "fallback" in the result.

Dependencies { .dependencies }

isbot { .dependency }

Bot detection library that compiles a comprehensive regex and automatically falls back to a naive heuristic when advanced regex features (like lookbehind) are unsupported.