0
# Lunr
1

2
Lunr is a lightweight, client-side full-text search library designed for browser-based applications that need to search through JSON documents without requiring server-side infrastructure. It provides a simple API for creating search indexes, supports advanced features like field-specific searches, term boosting, fuzzy matching with wildcards, and edit distance calculations.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
// ES6/CommonJS - Lunr works in both browser and Node.js
15
const lunr = require('lunr');
16

17
// Browser global
18
// <script src="path/to/lunr.js"></script>
19
// lunr is available globally
20
```
21

22
## Basic Usage
23

24
```javascript
25
const lunr = require('lunr');
26

27
// Create a search index
28
const idx = lunr(function () {
29
  this.ref('id');
30
  this.field('title');
31
  this.field('body');
32

33
  this.add({
34
    id: '1',
35
    title: 'Getting Started',
36
    body: 'This is a tutorial about getting started with Lunr.'
37
  });
38

39
  this.add({
40
    id: '2', 
41
    title: 'Advanced Features',
42
    body: 'Learn about advanced search features in Lunr.'
43
  });
44
});
45

46
// Search the index
47
const results = idx.search('tutorial');
48
// Returns: [{ ref: '1', score: 0.6931471805599453 }]
49

50
// Search with field-specific queries
51
const fieldResults = idx.search('title:Advanced');
52
// Returns: [{ ref: '2', score: 1.0986122886681098 }]
53
```
54

55
## Architecture
56

57
Lunr is built around several key components:
58

59
- **Index Building**: Core `lunr()` function and `Builder` class for creating searchable indexes from documents
60
- **Search Engine**: `Index` class providing query execution with scoring and ranking
61
- **Text Processing**: Configurable pipeline with stemming, stop word filtering, and tokenization
62
- **Query System**: Advanced query parser supporting field restrictions, wildcards, fuzzy matching, and boolean operators
63
- **Data Structures**: Optimized vector spaces, token sets, and finite state automata for efficient search operations
64

65
## Capabilities
66

67
### Index Building
68

69
Core functionality for creating search indexes from documents. The main entry point for building searchable indexes with customizable fields, reference keys, and text processing pipelines.
70

71
```javascript { .api }
72
/**
73
 * Create a new search index using the builder pattern
74
 * @param {Function} config - Configuration function that receives a Builder instance
75
 * @returns {lunr.Index} - Built search index ready for querying
76
 */
77
function lunr(config);
78

79
/**
80
 * Current version of the Lunr library
81
 * @type {string}
82
 */
83
lunr.version; // "2.3.9"
84
```
85

86
[Index Building](./index-building.md)
87

88
### Searching
89

90
Search execution engine providing query processing, scoring, and result ranking. Supports both simple string queries and advanced programmatic query building.
91

92
```javascript { .api }
93
class Index {
94
  /**
95
   * Search the index using query string syntax
96
   * @param {string} queryString - Query to search for, supports field restrictions, wildcards, etc.
97
   * @returns {Array<Object>} - Array of search results with ref and score
98
   */
99
  search(queryString);
100

101
  /**
102
   * Build queries programmatically for complex search logic
103
   * @param {Function} builderFunction - Function that receives a Query builder
104
   * @returns {Array<Object>} - Array of search results
105
   */
106
  query(builderFunction);
107

108
  /**
109
   * Serialize the index to JSON for storage/transmission
110
   * @returns {Object} - Serialized index data
111
   */
112
  toJSON();
113

114
  /**
115
   * Load an index from serialized JSON data
116
   * @param {Object} serializedIndex - Previously serialized index
117
   * @returns {lunr.Index} - Reconstructed index instance
118
   */
119
  static load(serializedIndex);
120
}
121
```
122

123
[Searching](./searching.md)
124

125
### Text Processing
126

127
Configurable text processing pipeline for tokenization, stemming, and filtering. Includes built-in processors and support for custom pipeline functions.
128

129
```javascript { .api }
130
/**
131
 * Built-in stemmer for reducing words to root forms
132
 * @param {lunr.Token} token - Token to stem
133
 * @returns {lunr.Token} - Stemmed token
134
 */
135
lunr.stemmer;
136

137
/**
138
 * Built-in stop word filter for removing common words
139
 * @param {lunr.Token} token - Token to filter
140
 * @returns {lunr.Token|undefined} - Token if not a stop word, undefined otherwise
141
 */
142
lunr.stopWordFilter;
143

144
/**
145
 * Built-in trimmer for removing non-word characters
146
 * @param {lunr.Token} token - Token to trim
147
 * @returns {lunr.Token} - Trimmed token
148
 */
149
lunr.trimmer;
150

151
/**
152
 * Default tokenizer for converting strings to tokens
153
 * @param {string|Object} obj - String or object to tokenize
154
 * @param {Object} metadata - Optional metadata to attach to tokens
155
 * @returns {Array<lunr.Token>} - Array of tokens
156
 */
157
lunr.tokenizer;
158
```
159

160
[Text Processing](./text-processing.md)
161

162
### Advanced Querying
163

164
Advanced query construction and parsing capabilities. Supports field restrictions, wildcards, fuzzy matching, edit distance, boolean operators, and term boosting.
165

166
```javascript { .api }
167
class Query {
168
  /**
169
   * Add a clause to the query
170
   * @param {Object} clause - Query clause with term, field, and options
171
   * @returns {lunr.Query} - Query instance for chaining
172
   */
173
  clause(clause);
174

175
  /**
176
   * Add a term to the query with options
177
   * @param {string} term - Search term
178
   * @param {Object} options - Term options (field, boost, wildcard, etc.)
179
   * @returns {lunr.Query} - Query instance for chaining
180
   */
181
  term(term, options);
182

183
  /**
184
   * Check if the query is negated
185
   * @returns {boolean} - True if query is negated
186
   */
187
  isNegated();
188
}
189

190
// Query constants for wildcard insertion
191
lunr.Query.wildcard = {
192
  NONE: 0,      // No wildcards
193
  LEADING: 1,   // Leading wildcard (e.g., "*term")
194
  TRAILING: 2   // Trailing wildcard (e.g., "term*")
195
};
196

197
// Query constants for term presence
198
lunr.Query.presence = {
199
  OPTIONAL: 1,   // Term is optional (default)
200
  REQUIRED: 2,   // Term must be present (+term)
201
  PROHIBITED: 3  // Term must not be present (-term)
202
};
203
```
204

205
[Advanced Querying](./advanced-querying.md)
206

207
### Utilities
208

209
Utility functions and data structures used throughout the library. Includes helper functions, error handling, and internal data structures.
210

211
```javascript { .api }
212
// Utility namespace
213
lunr.utils = {
214
  /**
215
   * Print warning message to console
216
   * @param {string} message - Warning message
217
   */
218
  warn(message),
219

220
  /**
221
   * Convert object to string, handling null/undefined
222
   * @param {*} obj - Object to convert
223
   * @returns {string} - String representation
224
   */
225
  asString(obj),
226

227
  /**
228
   * Shallow clone objects and arrays
229
   * @param {*} obj - Object to clone
230
   * @returns {*} - Cloned object
231
   */
232
  clone(obj)
233
};
234

235
/**
236
 * Calculate inverse document frequency for scoring
237
 * @param {Object} posting - Term posting information
238
 * @param {number} documentCount - Total number of documents
239
 * @returns {number} - IDF score
240
 */
241
lunr.idf(posting, documentCount);
242
```
243

244
[Utilities](./utilities.md)
245

246
## Common Patterns
247

248
### Creating Indexes with Custom Configuration
249

250
```javascript
251
const idx = lunr(function () {
252
  // Set document reference field (default: 'id')
253
  this.ref('documentId');
254
  
255
  // Add fields with optional boost values
256
  this.field('title', { boost: 10 });
257
  this.field('body');
258
  this.field('tags', { boost: 5 });
259
  
260
  // Configure search parameters
261
  this.b(0.75);  // Field length normalization (0-1)
262
  this.k1(1.2);  // Term frequency saturation
263
  
264
  // Add documents
265
  documents.forEach(function (doc) {
266
    this.add(doc);
267
  }, this);
268
});
269
```
270

271
### Advanced Search Queries
272

273
```javascript
274
// Field-specific search
275
idx.search('title:advanced');
276

277
// Wildcard search
278
idx.search('run*');      // Terms starting with "run"
279
idx.search('*ing');      // Terms ending with "ing"
280

281
// Fuzzy search with edit distance
282
idx.search('tutorial~1'); // Allow 1 character difference
283

284
// Boolean queries
285
idx.search('+required -forbidden optional');
286

287
// Term boosting
288
idx.search('important^10 normal');
289
```
290

291
### Index Serialization
292

293
```javascript
294
// Serialize index for storage
295
const serialized = idx.toJSON();
296
localStorage.setItem('searchIndex', JSON.stringify(serialized));
297

298
// Load index from storage
299
const storedIndex = JSON.parse(localStorage.getItem('searchIndex'));
300
const idx = lunr.Index.load(storedIndex);
301
```