feat(search): Improve search query handling and update documentation

ts/00_commitinfo_data.ts

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

ts/classes.doc.ts

@@ -452,6 +452,30 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
       });
       return await (this as any).execQuery({ $and: andConds }, opts);
     }
+
+    // free term and quoted field phrase (exact or wildcard), e.g. 'term field:"phrase"' or 'term field:"ph*se"'
+    const freeWithQuotedField = q.match(/^(\S+)\s+(\w+):"(.+)"$/);
+    if (freeWithQuotedField) {
+      const freeTerm = freeWithQuotedField[1];
+      const field = freeWithQuotedField[2];
+      let phrase = freeWithQuotedField[3];
+      if (!searchableFields.includes(field)) {
+        throw new Error(`Field '${field}' is not searchable for class ${this.name}`);
+      }
+      // free term condition across all searchable fields
+      const freeEsc = escapeForRegex(freeTerm);
+      const freeCond = { $or: searchableFields.map((f) => ({ [f]: { $regex: freeEsc, $options: 'i' } })) };
+      // field condition: exact match or wildcard pattern
+      let fieldCond;
+      if (phrase.includes('*') || phrase.includes('?')) {
+        const escaped = phrase.replace(/([.+^${}()|[\\]\\])/g, '\\$1');
+        const pattern = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+        fieldCond = { [field]: { $regex: pattern, $options: 'i' } };
+      } else {
+        fieldCond = { [field]: phrase };
+      }
+      return await (this as any).execQuery({ $and: [freeCond, fieldCond] }, opts);
+    }
     // detect advanced Lucene syntax: field:value, wildcards, boolean, grouping
     const luceneSyntax = /(\w+:[^\s]+)|\*|\?|\bAND\b|\bOR\b|\bNOT\b|\(|\)/;
     if (luceneSyntax.test(q)) {