0
# isbot
1

2
isbot is a comprehensive bot detection library that identifies bots, crawlers, and spiders by analyzing user agent strings. It provides both simple boolean detection and advanced pattern matching capabilities, supporting multiple JavaScript environments with high accuracy and zero runtime dependencies.
3

4
## Package Information
5

6
- **Package Name**: isbot
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install isbot`
10

11
## Core Imports
12

13
```javascript
14
import { isbot } from "isbot";
15
```
16

17
For all exports:
18

19
```javascript
20
import { 
21
  isbot, 
22
  isbotNaive, 
23
  isbotMatch, 
24
  isbotMatches, 
25
  isbotPattern, 
26
  isbotPatterns,
27
  createIsbot, 
28
  createIsbotFromList, 
29
  getPattern, 
30
  list 
31
} from "isbot";
32
```
33

34
CommonJS:
35

36
```javascript
37
const { isbot } = require("isbot");
38
const { isbot, list, createIsbot } = require("isbot");
39
```
40

41
Browser (global):
42

43
```html
44
<script src="https://cdn.jsdelivr.net/npm/isbot@5.1.30/index.iife.js"></script>
45
<script>
46
  console.log(isbot(navigator.userAgent));
47
</script>
48
```
49

50
## Basic Usage
51

52
```javascript
53
import { isbot } from "isbot";
54

55
// Basic bot detection
56
const userAgent = "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)";
57
console.log(isbot(userAgent)); // true
58

59
// Real browser user agent
60
const browserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36";
61
console.log(isbot(browserAgent)); // false
62

63
// Handle null/undefined gracefully
64
console.log(isbot(null)); // false
65
console.log(isbot(undefined)); // false
66
console.log(isbot("")); // false
67
```
68

69
## Architecture
70

71
isbot is built around several key components:
72

73
- **Pattern Engine**: Comprehensive regex patterns compiled from a curated list of bot identifiers
74
- **Fallback System**: Naive pattern matching as fallback for environments with regex limitations
75
- **Factory Functions**: Customizable bot detection with user-defined patterns
76
- **Multiple Exports**: Support for CommonJS, ESM, and browser environments
77
- **Zero Dependencies**: Standalone library with no external dependencies
78

79
## Capabilities
80

81
### Core Bot Detection
82

83
Primary bot detection functionality using comprehensive pattern matching.
84

85
```javascript { .api }
86
/**
87
 * Check if the given user agent includes a bot pattern.
88
 * Uses comprehensive pattern matching for high accuracy.
89
 */
90
function isbot(userAgent?: string | null): boolean;
91
```
92

93
### Naive Bot Detection
94

95
Fast, simple bot detection using basic pattern matching.
96

97
```javascript { .api }
98
/**
99
 * Check if the given user agent includes a bot pattern. 
100
 * Naive implementation (less accurate but faster).
101
 */
102
const isbotNaive: (userAgent?: string | null) => boolean;
103
```
104

105
### Pattern Matching
106

107
Find specific parts of user agents that match bot patterns.
108

109
```javascript { .api }
110
/**
111
 * Find the first part of the user agent that matches a bot pattern.
112
 */
113
const isbotMatch: (userAgent?: string | null) => string | null;
114

115
/**
116
 * Find all parts of the user agent that match bot patterns.
117
 */
118
const isbotMatches: (userAgent?: string | null) => string[];
119
```
120

121
### Pattern Discovery
122

123
Identify which specific patterns from the bot list match a user agent.
124

125
```javascript { .api }
126
/**
127
 * Find the first bot pattern that matches the given user agent.
128
 */
129
const isbotPattern: (userAgent?: string | null) => string | null;
130

131
/**
132
 * Find all bot patterns that match the given user agent.
133
 */
134
const isbotPatterns: (userAgent?: string | null) => string[];
135
```
136

137
**Usage Examples:**
138

139
```javascript
140
import { isbotMatch, isbotMatches, isbotPattern, isbotPatterns } from "isbot";
141

142
const botUA = "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)";
143

144
// Find first matching substring using compiled pattern
145
console.log(isbotMatch(botUA)); // "google" (first match from combined pattern)
146

147
// Find all matching substrings from individual patterns
148
console.log(isbotMatches(botUA)); // ["google", "bot", "compatible"] (various matches)
149

150
// Find first matching pattern string from the pattern list
151
console.log(isbotPattern(botUA)); // "(?<! (?:channel/|google/))google(?!(app|/google| pixel))"
152

153
// Find all matching pattern strings from the pattern list
154
console.log(isbotPatterns(botUA)); // Array of pattern strings that match
155
```
156

157
### Custom Bot Detection
158

159
Create custom bot detection functions with user-defined patterns.
160

161
```javascript { .api }
162
/**
163
 * Create a custom isbot function with a custom RegExp pattern.
164
 */
165
const createIsbot: (customPattern: RegExp) => ((userAgent?: string | null) => boolean);
166

167
/**
168
 * Create a custom isbot function from a list of pattern strings.
169
 * @param list - Array of regex pattern strings to match against user agents
170
 */
171
const createIsbotFromList: (list: string[]) => ((userAgent?: string | null) => boolean);
172
```
173

174
**Usage Examples:**
175

176
```javascript
177
import { createIsbot, createIsbotFromList } from "isbot";
178

179
// Custom regex pattern
180
const customBot = createIsbot(/my-custom-bot|special-crawler/i);
181
console.log(customBot("My-Custom-Bot/1.0")); // true
182
console.log(customBot(null)); // false - handles null/undefined gracefully
183

184
// From pattern list - array of regex pattern strings
185
const socialBots = createIsbotFromList([
186
  "facebookexternalhit",
187
  "twitterbot", 
188
  "linkedinbot"
189
]);
190
console.log(socialBots("facebookexternalhit/1.1")); // true
191
console.log(socialBots("")); // false - handles empty strings gracefully
192
```
193

194
### Pattern Access
195

196
Access to the underlying patterns and regex used for detection.
197

198
```javascript { .api }
199
/**
200
 * Returns the compiled RegExp pattern used for bot detection.
201
 * Falls back to naive pattern if compilation fails.
202
 */
203
function getPattern(): RegExp;
204

205
/**
206
 * A list of bot identifiers used in regular expressions against user agent strings.
207
 */
208
const list: string[];
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
import { getPattern, list } from "isbot";
215

216
// Get the compiled pattern
217
const pattern = getPattern();
218
console.log(pattern.test("Googlebot/2.1")); // true
219

220
// Access pattern list - contains regex pattern strings
221
console.log(list.length); // 200+ regex patterns
222
console.log(list.includes("(?<! (?:channel/|google/))google(?!(app|/google| pixel))")); // true
223

224
// Use patterns directly
225
const hasGooglePattern = list.some(patternStr => 
226
  new RegExp(patternStr, "i").test("Googlebot/2.1 (+http://www.google.com/bot.html)")
227
); // true
228
```
229

230
## Error Handling
231

232
isbot handles edge cases gracefully:
233

234
- **Null/undefined user agents**: Returns `false` safely
235
- **Empty strings**: Returns `false`
236
- **Invalid regex patterns**: Falls back to naive pattern matching
237
- **Older JavaScript engines**: Graceful degradation to simple pattern matching
238

239
```javascript
240
import { isbot } from "isbot";
241

242
// All return false safely
243
console.log(isbot(null));      // false
244
console.log(isbot(undefined)); // false  
245
console.log(isbot(""));        // false
246
```
247

248
## Types
249

250
```typescript { .api }
251
// Main detection function
252
declare function isbot(userAgent?: string | null): boolean;
253

254
// Naive detection
255
declare const isbotNaive: (userAgent?: string | null) => boolean;
256

257
// Pattern matching functions
258
declare const isbotMatch: (userAgent?: string | null) => string | null;
259
declare const isbotMatches: (userAgent?: string | null) => string[];
260
declare const isbotPattern: (userAgent?: string | null) => string | null;
261
declare const isbotPatterns: (userAgent?: string | null) => string[];
262

263
// Factory functions
264
declare const createIsbot: (customPattern: RegExp) => ((userAgent?: string | null) => boolean);
265
declare const createIsbotFromList: (list: string[]) => ((userAgent?: string | null) => boolean);
266

267
// Utility functions
268
declare function getPattern(): RegExp;
269
declare const list: string[];
270
```