Implement options and add new tests

Author: ECRomaneli

README.md

@@ -1,47 +1,19 @@
 # Search-Engine
 
-A lightweight, powerful object search engine for JavaScript with advanced query syntax
+A lightweight, powerful object search engine for JavaScript with advanced query syntax.
 
 <p>
-    <a href="https://github.com/ECRomaneli/Search-Engine/tags"><img src="https://img.shields.io/github/v/tag/ecromaneli/Search-Engine?label=version&sort=semver" alt="Version"></a>
-    <a href="https://github.com/ECRomaneli/Search-Engine/commits/master"><img src="https://img.shields.io/github/last-commit/ecromaneli/Search-Engine" alt="Last Commit"></a>
-    <a href="https://github.com/ECRomaneli/Search-Engine/blob/master/LICENSE"><img src="https://img.shields.io/github/license/ecromaneli/Search-Engine" alt="License"></a>
-    <a href="https://github.com/ECRomaneli/Search-Engine/issues"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg" alt="Contributions Welcome"></a>
+<a href="https://github.com/ECRomaneli/Search-Engine/tags"><img src="https://img.shields.io/github/v/tag/ecromaneli/Search-Engine?label=version&sort=semver" alt="Version"></a>
+<a href="https://github.com/ECRomaneli/Search-Engine/commits/master"><img src="https://img.shields.io/github/last-commit/ecromaneli/Search-Engine" alt="Last Commit"></a>
+<a href="https://github.com/ECRomaneli/Search-Engine/blob/master/LICENSE"><img src="https://img.shields.io/github/license/ecromaneli/Search-Engine" alt="License"></a>
+<a href="https://github.com/ECRomaneli/Search-Engine/issues"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg" alt="Contributions Welcome"></a>
 </p>
 
 ## Installation
 
 ```bash
 npm install @ecromaneli/search-engine
-```
-
-## Download
-
-For browser usage, you can download and use the pre-built version:
-
-1. Go to the [Releases page](https://github.com/ECRomaneli/Search-Engine/releases/latest)
-2. Download the `search-engine-web.zip` file 
-3. Extract the ZIP and include the script in your HTML:
-
-```html
-<!-- Include the script in your HTML file -->
-<script src="path/to/search-engine.js"></script>
-<!-- Or use the minified version -->
-<!-- <script src="path/to/search-engine.min.js"></script> -->
-
-<script>
-  // Sample data
-  const users = [
-    { id: 1, name: 'John Doe', age: 28, tags: ['developer', 'javascript'] },
-    { id: 2, name: 'Jane Smith', age: 34, tags: ['designer', 'ui/ux'] },
-    { id: 3, name: 'Bob Johnson', age: 45, tags: ['manager', 'finance'] }
-  ];
-  
-  // Use SearchEngine.search() directly
-  const results = SearchEngine.search(users, 'name:john');
-  console.log(results);
-</script>
-```
+``` 
 
 ## Features
 
@@ -52,69 +24,149 @@ For browser usage, you can download and use the pre-built version:
 - Logical negation of search terms
 - Nested property searching
 - Logical grouping with parentheses
+- Customizable search options
 - Zero dependencies
 
 ## Basic Usage
 
 ```javascript
-const { search } = require('@ecromaneli/search-engine')
+const { SearchEngine } = require('@ecromaneli/search-engine')
 
-// Sample data
 const users = [
   { id: 1, name: 'John Doe', age: 28, tags: ['developer', 'javascript'] },
   { id: 2, name: 'Jane Smith', age: 34, tags: ['designer', 'ui/ux'] },
   { id: 3, name: 'Bob Johnson', age: 45, tags: ['manager', 'finance'] }
 ]
 
-// Simple search
-const result1 = search(users, '"john"')  // Find users with "john" in any field
+const result = SearchEngine.search(users, 'name: john')
+console.log(result)
+```
 
-// Field-specific search
-const result2 = search(users, 'name:jane')  // Find users with "jane" in the name field
+## Using the SearchEngine Constructor
 
-// Age range search
-const result3 = search(users, 'age~:25-35')  // Find users with age between 25 and 35
+You can create a `SearchEngine` instance with specific options that will be used for all searches:
 
-// Complex search with boolean operators and grouping
-const result4 = search(users, '("developer" or "designer") and not age~:40-50')
+```javascript
+const engine = new SearchEngine({
+  excludeKeys: ['password', 'private.info'],
+  allowNumericString: false,
+  allowKeyValueMatching: true,
+  matchChildKeysAsValues: false
+})
+
+const results = engine.search(users, 'age~: 25-35')
+console.log(results)
 ```
 
+## Search Options
+
+The `SearchOptions` object allows you to customize the behavior of the search engine. Below is a table explaining each option:
+
+| Option                   | Type       | Default | Description                                                                                     |
+|--------------------------|------------|---------|-------------------------------------------------------------------------------------------------|
+| `excludeKeys`            | `string[]` | `[]`    | Array of keys to exclude from search. Useful for excluding sensitive data.                      |
+| `allowNumericString`     | `boolean`  | `true`  | Controls whether string values that can be parsed as numbers are used in range searches.        |
+| `allowKeyValueMatching`  | `boolean`  | `true`  | When enabled, unquoted terms without a field/value separator match both field names and values. |
+| `matchChildKeysAsValues` | `boolean`  | `false` | When enabled, after finding a matching key, also looks for the value in child object keys.      |
+
+### Differences Between Options
+
+- **`allowNumericString`**:
+  - When `true`, strings like `"123"` will be treated as numbers in range searches.
+  - When `false`, only actual numbers will be considered for range searches.
+
+- **`allowKeyValueMatching`**:
+  - When `true`, a query like `"admin"` will match both `{ admin: "value" }` and `{ key: "admin" }`.
+  - When `false`, it will only match field names or values explicitly.
+
+- **`matchChildKeysAsValues`**:
+  - When `true`, a query like `"foo:bar"` will match both `{ foo: "bar" }` and `{ foo: { bar: "value" } }`.
+  - When `false`, it will only match `{ foo: "bar" }`.
+
 ## Query Syntax Reference
 
 ### Basic Queries
 
-- `field` - Search for "field" with any value
-- `"value"` - Search for "value" in any field
-- `field:value` - Search for "value" in the specific field
+- `foo` - Search for objects having a field or value `foo`.
+- `"value"` - Search for `"value"` in any field.
+- `field: value` - Search for `value` in the specific `field`.
 
 ### Specialized Searches
 
-- `field*:pattern` - Regex pattern match on field
-- `field~:min-max` - Numeric range search (min and max are optional)
+- `field*: pattern` - Regex pattern match on field.
+- `field~: min-max` - Numeric range search.
+- `field~: 10-` - Numbers greater than or equal to 10.
+- `field~: -20` - Numbers less than or equal to 20.
+
+Negative values are also supported.
 
 ### Boolean Operators
 
-- `term1 and term2` - Both terms must match
-- `term1 or term2` - Either term must match
+- `term1 and term2` - Both terms must match.
+- `term1 or term2` - Either term must match.
 
 ### Negation and Grouping
 
-- `not term` - Term must not match
-- `not (term1 or term2) and term3` - Logical grouping with parentheses
+- `not term` - Term must not match.
+- `not (term1 or term2)` - Group negation (neither term1 nor term2 should match).
+- `(term1 or term2) and term3` - Logical grouping with parentheses.
 
 ## API Reference
 
-### search(objList, queryStr, exclude)
+### Static Methods
+
+#### `SearchEngine.search(objList, queryStr, options)`
+
+- **`objList`** (`Array`): Array of objects to search through.
+- **`queryStr`** (`String`): Query string following the syntax described above.
+- **`options`** (`Object`, optional): Search options object.
+- **Returns** (`Array`): Array of matching objects.
+
+### Instance Methods
+
+To store the options, use the constructor below:
+
+#### `new SearchEngine(options)`
+
+- **`options`** (`Object`, optional): Search options object (see Options table).
+- **Returns** (`SearchEngine`): A new `SearchEngine` instance with the specified options.
+
+#### `searchInstance.search(objList, queryStr)`
+
+- **`objList`** (`Array`): Array of objects to search through.
+- **`queryStr`** (`String`): Query string following the syntax described above.
+- **Returns** (`Array`): Array of matching objects with the instance's options applied.
+
+## Performance Tips
+
+- For large datasets, consider disabling `allowNumericString` if you don't need string-to-number conversion.
+- Set `matchChildKeysAsValues: false` (default) unless you specifically need to match object keys as values.
+- Use `excludeKeys` to skip searching in fields that are never relevant to your searches.
+- For repeated searches with the same options, create a `SearchEngine` instance instead of using the static method.
+
+## Examples and Advanced Usage
+
+For a comprehensive set of usage examples covering all search engine features, refer to our test suite:
+
+[View Test Examples](test/index.test.js)
+
+The test file includes examples of:
+- Complex nested property searching
+- Array item searching
+- Logical grouping with parentheses
+- De Morgan's law transformations
+- Complex boolean expressions
+- Excluded keys functionality
+- Range searches with various configurations
+- Quoted values with special characters
+- Edge cases and error handling
 
-- **objList** (Array): Array of objects to search through
-- **queryStr** (String): Query string following the syntax described above
-- **exclude** (Array, optional): Array of property names to exclude from searching
-- **Returns** (Array): Array of matching objects
+These examples serve as excellent reference implementations when building advanced search queries.
 
 ## Author
 
-Created by [Emerson Capuchi Romaneli](https://github.com/ECRomaneli) (@ECRomaneli).
+Created by Emerson Capuchi Romaneli (@ECRomaneli).
 
 ## License
 
-This project is licensed under the [MIT License](https://github.com/ECRomaneli/Search-Engine/blob/master/LICENSE).
+This project is licensed under the MIT License.