fix(documentation): Update search API documentation to replace deprecated searchWithLucene examples with the unified search(query) API and clarify its behavior.

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2025-04-18 - 5.9.2 - fix(documentation)
+Update search API documentation to replace deprecated searchWithLucene examples with the unified search(query) API and clarify its behavior.
+
+- Replaced 'searchWithLucene' examples with 'search(query)' in the README.
+- Updated explanation to detail field-specific exact match, partial word regex search, multi-word literal matching, and handling of empty queries.
+- Clarified guidelines for creating MongoDB text indexes on searchable fields for optimized search performance.
+
 ## 2025-04-18 - 5.9.1 - fix(search)
 Refactor search tests to use unified search API and update text index type casting
 

readme.md

@@ -18,7 +18,7 @@ A powerful TypeScript-first MongoDB wrapper that provides advanced features for
 - **Enhanced Cursors**: Chainable, type-safe cursor API with memory efficient data processing
 - **Type Conversion**: Automatic handling of MongoDB types like ObjectId and Binary data
 - **Serialization Hooks**: Custom serialization and deserialization of document properties
-- **Powerful Search Capabilities**: Lucene-like query syntax with field-specific search, advanced operators, and fallback mechanisms
+- **Powerful Search Capabilities**: Unified `search(query)` API supporting field:value exact matches, multi-field regex searches, case-insensitive matching, and automatic escaping to prevent regex injection
 
 ## Requirements
 
@@ -218,43 +218,31 @@ class Product extends SmartDataDbDoc<Product, Product> {
 const searchableFields = getSearchableFields('Product'); // ['name', 'description', 'category']
 
 // Basic search across all searchable fields
-const iPhoneProducts = await Product.searchWithLucene('iPhone');
+const iphoneProducts = await Product.search('iPhone');
 
-// Field-specific search
+// Field-specific exact match
-const electronicsProducts = await Product.searchWithLucene('category:Electronics');
+const electronicsProducts = await Product.search('category:Electronics');
 
-// Search with wildcards
+// Partial word search (regex across all fields)
-const macProducts = await Product.searchWithLucene('Mac*');
+const laptopResults = await Product.search('laptop');
 
-// Search in specific fields with partial words
+// Multi-word literal search
-const laptopResults = await Product.searchWithLucene('description:laptop');
+const paperwhite = await Product.search('Kindle Paperwhite');
 
-// Search is case-insensitive
+// Empty query returns all documents
-const results1 = await Product.searchWithLucene('electronics');
+const allProducts = await Product.search('');
-const results2 = await Product.searchWithLucene('Electronics');
-// results1 and results2 will contain the same documents
-
-// Using boolean operators (requires text index in MongoDB)
-const wirelessOrLaptop = await Product.searchWithLucene('wireless OR laptop');
-
-// Negative searches
-const electronicsNotSamsung = await Product.searchWithLucene('Electronics NOT Samsung');
-
-// Phrase searches
-const exactPhrase = await Product.searchWithLucene('"high-speed blender"');
-
-// Grouping with parentheses
-const complexQuery = await Product.searchWithLucene('(wireless OR bluetooth) AND Electronics');
 ```
 
 The search functionality includes:
 
 - `@searchable()` decorator for marking fields as searchable
-- `getSearchableFields()` to retrieve all searchable fields for a class
+- `getSearchableFields()` to list searchable fields for a model
-- `search()` method for basic search (requires MongoDB text index)
+- `search(query: string)` method supporting:
-- `searchWithLucene()` method with robust fallback mechanisms
+  - Field-specific exact matches (`field:value`)
-- Support for field-specific searches, wildcards, and boolean operators
+  - Case-insensitive partial matches across all searchable fields
-- Automatic fallback to regex-based search if MongoDB text search fails
+  - Multi-word literal matching
+  - Empty queries returning all documents
+- Automatic escaping of special characters to prevent regex injection
 
 ### EasyStore
 
@@ -549,10 +537,10 @@ class Order extends SmartDataDbDoc<Order, Order> {
 
 ### Search Optimization
 
-- Create MongoDB text indexes for collections that need advanced search operations
+- (Optional) Create MongoDB text indexes on searchable fields to speed up full-text search
-- Use `searchWithLucene()` for robust searches with fallback mechanisms
+- Use `search(query)` for all search operations (field:value, partial matches, multi-word)
-- Prefer field-specific searches when possible for better performance
+- Prefer field-specific exact matches when possible for optimal performance
-- Use simple term queries instead of boolean operators if you don't have text indexes
+- Avoid unnecessary complexity in query strings to keep regex searches efficient
 
 ### Performance Optimization
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdata',
-  version: '5.9.1',
+  version: '5.9.2',
   description: 'An advanced library for NoSQL data organization and manipulation using TypeScript with support for MongoDB, data validation, collections, and custom data types.'
 }