feat: extract BuildFuzzinessQueryClauses as public API (#266)

* feat: extract BuildFuzzinessQueryClauses as public API

* Extract the fuzziness query construction logic from buildFuzzinessQuery()
  into a reusable public function. This allows clients to build custom
  hybrid or semantic searches while reusing the framework's fuzziness
  query logic.

* Refactor buildFuzzinessQuery() to use BuildFuzzinessQueryClauses()

* Add SetFuzzinessBuilt() setter to allow clients to skip built-in
  fuzziness query construction when handling it themselves

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: error out if fuzziness is invalid

* chore: release notes

* test: test BuildFuzzinessQueryClauses()

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: SteveLauC

core/orm/query.go

@@ -207,6 +207,14 @@ func (q *QueryBuilder) FuzzinessVal() int {
 	return q.fuzziness
 }
 
+// SetFuzzinessBuilt marks whether the fuzziness query has been built.
+// By default, the ORM handles fuzziness query construction automatically.
+// Use this method to skip the built-in fuzziness logic when you want to
+// handle it yourself.
+func (q *QueryBuilder) SetFuzzinessBuilt(built bool) {
+	q.builtFuzziness = built
+}
+
 func (q *QueryBuilder) IncludesVal() []string {
 	return q.includes
 }
@@ -703,18 +711,23 @@ func getClausesByType(c *Clause, typ BoolType) []*Clause {
 		return nil
 	}
 }
-func (q *QueryBuilder) buildFuzzinessQuery() {
-	if q.builtFuzziness {
-		return
-	}
-	q.builtFuzziness = true
 
-	queryStr := q.QueryVal()
-	if queryStr == "" {
-		return
+// BuildFuzzinessQueryClauses builds query clauses based on fuzziness level.
+//
+// Parameters:
+//   - queryStr: the search query string (e.g., "mysql" or "title^2:mysql")
+//   - fuzziness: fuzziness level (0-5)
+//   - defaultFields: default fields to search when no explicit field is specified
+//     in the queryStr
+//
+// Returns a slice of Clause objects and an error if fuzziness is invalid:
+//   - Single-element slice: use directly (e.g., q.Must(clauses[0]))
+//   - Multiple-element slice: wrap in ShouldQuery (e.g., q.Must(ShouldQuery(clauses...)))
+func BuildFuzzinessQueryClauses(queryStr string, fuzziness int, defaultFields []string) ([]*Clause, error) {
+	if fuzziness < 0 || fuzziness > 5 {
+		return nil, fmt.Errorf("invalid fuzziness value: %d, must be between 0 and 5", fuzziness)
 	}
 
-	fuzzinessVal := q.FuzzinessVal()
 	field, value := parseQuery(queryStr)
 
 	// Case 1: Explicit field is provided (possibly with ^boost)
@@ -732,43 +745,42 @@ func (q *QueryBuilder) buildFuzzinessQuery() {
 		// Helper to apply overall boost
 		boost := func(base float32) float32 { return base * fieldBoost }
 
-		switch fuzzinessVal {
+		switch fuzziness {
 		case 0, 1:
-			q.Must(MatchQuery(field, value).SetBoost(boost(1)))
+			return []*Clause{MatchQuery(field, value).SetBoost(boost(1))}, nil
 		case 2:
-			q.Must(ShouldQuery(
+			return []*Clause{
 				MatchQuery(field, value).SetBoost(boost(5)),
 				PrefixQuery(field, value).SetBoost(boost(2)),
-			))
+			}, nil
 		case 3:
-			q.Must(ShouldQuery(
+			return []*Clause{
 				MatchQuery(field, value).SetBoost(boost(5)),
 				PrefixQuery(field, value).SetBoost(boost(3)),
 				MatchPhraseQuery(field, value, 0).SetBoost(boost(2)),
-			))
+			}, nil
 		case 4:
-			q.Must(ShouldQuery(
+			return []*Clause{
 				MatchQuery(field, value).SetBoost(boost(5)),
 				PrefixQuery(field, value).SetBoost(boost(3)),
 				MatchPhraseQuery(field, value, 1).SetBoost(boost(2)),
 				FuzzyQuery(field, value, 1).SetBoost(boost(1)),
-			))
+			}, nil
 		case 5:
-			q.Must(ShouldQuery(
+			return []*Clause{
 				MatchQuery(field, value).SetBoost(boost(5)),
 				PrefixQuery(field, value).SetBoost(boost(3)),
 				MatchPhraseQuery(field, value, 2).SetBoost(boost(2)),
 				FuzzyQuery(field, value, 2).SetBoost(boost(1)),
-			))
+			}, nil
 		}
-		return
+		return nil, fmt.Errorf("invalid fuzziness value: %d", fuzziness)
 	}
 
 	// Case 2: No specific field, use default query fields
 	if value == "" {
 		value = queryStr
 	}
-	defaultFields := q.DefaultQueryFieldsVal()
 	shouldClauses := make([]*Clause, 0, len(defaultFields)*4)
 
 	for _, rawField := range defaultFields {
@@ -785,7 +797,7 @@ func (q *QueryBuilder) buildFuzzinessQuery() {
 
 		boost := func(base float32) float32 { return base * fieldBoost }
 
-		switch fuzzinessVal {
+		switch fuzziness {
 		case 0, 1:
 			shouldClauses = append(shouldClauses,
 				MatchQuery(field, value).SetBoost(boost(1)),
@@ -818,12 +830,33 @@ func (q *QueryBuilder) buildFuzzinessQuery() {
 		}
 	}
 
-	if len(shouldClauses) > 0 {
-		if len(shouldClauses) == 1 {
-			q.Must(shouldClauses[0])
-		} else {
-			q.Must(ShouldQuery(shouldClauses...))
-		}
+	return shouldClauses, nil
+}
+
+func (q *QueryBuilder) buildFuzzinessQuery() {
+	if q.builtFuzziness {
+		return
+	}
+	q.builtFuzziness = true
+
+	queryStr := q.QueryVal()
+	if queryStr == "" {
+		return
+	}
+
+	fuzzinessVal := q.FuzzinessVal()
+	defaultFields := q.DefaultQueryFieldsVal()
+
+	clauses, err := BuildFuzzinessQueryClauses(queryStr, fuzzinessVal, defaultFields)
+	if err != nil {
+		// Should be unreachable as fuzzinessVal is guaranteed to be valid (0-5)
+		panic(fmt.Sprintf("buildFuzzinessQuery failed: %v", err))
+	}
+
+	if len(clauses) == 1 {
+		q.Must(clauses[0])
+	} else if len(clauses) > 1 {
+		q.Must(ShouldQuery(clauses...))
 	}
 }
 

core/orm/query_test.go

@@ -71,6 +71,9 @@ func TestBoolQueryWrapping(t *testing.T) {
 	if len(boolClause.MustClauses) != 2 {
 		t.Errorf("Invalid BoolQuery: %+v", boolClause)
 	}
+	// Assert clause types
+	assert.Equal(t, QueryTerm, boolClause.MustClauses[0].Operator)
+	assert.Equal(t, QueryTerm, boolClause.MustClauses[1].Operator)
 }
 
 func TestMustQuery(t *testing.T) {
@@ -304,3 +307,134 @@ func TestSimplify_NoOpEmptyClause(t *testing.T) {
 		t.Errorf("Expected clause with field 'name', got %s", simplified.Field)
 	}
 }
+
+func TestBuildFuzzinessQueryClauses(t *testing.T) {
+	tests := []struct {
+		name            string
+		queryStr        string
+		fuzziness       int
+		defaultFields   []string
+		wantClauseLen   int
+		wantClauseTypes []QueryType
+	}{
+		{
+			name:            "fuzziness 0 - explicit field",
+			queryStr:        "title:mysql",
+			fuzziness:       0,
+			defaultFields:   []string{"title", "summary"},
+			wantClauseLen:   1,
+			wantClauseTypes: []QueryType{QueryMatch},
+		},
+		{
+			name:            "fuzziness 1 - explicit field",
+			queryStr:        "title:mysql",
+			fuzziness:       1,
+			defaultFields:   []string{"title", "summary"},
+			wantClauseLen:   1,
+			wantClauseTypes: []QueryType{QueryMatch},
+		},
+		{
+			name:            "fuzziness 2 - explicit field",
+			queryStr:        "title:mysql",
+			fuzziness:       2,
+			defaultFields:   []string{"title", "summary"},
+			wantClauseLen:   2,
+			wantClauseTypes: []QueryType{QueryMatch, QueryPrefix},
+		},
+		{
+			name:            "fuzziness 3 - explicit field",
+			queryStr:        "title:mysql",
+			fuzziness:       3,
+			defaultFields:   []string{"title", "summary"},
+			wantClauseLen:   3,
+			wantClauseTypes: []QueryType{QueryMatch, QueryPrefix, QueryMatchPhrase},
+		},
+		{
+			name:            "fuzziness 4 - explicit field",
+			queryStr:        "title:mysql",
+			fuzziness:       4,
+			defaultFields:   []string{"title", "summary"},
+			wantClauseLen:   4,
+			wantClauseTypes: []QueryType{QueryMatch, QueryPrefix, QueryMatchPhrase, QueryFuzzy},
+		},
+		{
+			name:            "fuzziness 5 - explicit field",
+			queryStr:        "title:mysql",
+			fuzziness:       5,
+			defaultFields:   []string{"title", "summary"},
+			wantClauseLen:   4,
+			wantClauseTypes: []QueryType{QueryMatch, QueryPrefix, QueryMatchPhrase, QueryFuzzy},
+		},
+		{
+			name:          "fuzziness 3 - default fields",
+			queryStr:      "mysql",
+			fuzziness:     3,
+			defaultFields: []string{"title", "summary"},
+			wantClauseLen: 6,
+			wantClauseTypes: []QueryType{
+				QueryMatch, QueryPrefix, QueryMatchPhrase, // title
+				QueryMatch, QueryPrefix, QueryMatchPhrase, // summary
+			},
+		},
+		{
+			name:            "fuzziness 3 - with field boost",
+			queryStr:        "title^2:mysql",
+			fuzziness:       3,
+			defaultFields:   []string{"title"},
+			wantClauseLen:   3,
+			wantClauseTypes: []QueryType{QueryMatch, QueryPrefix, QueryMatchPhrase},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			clauses, err := BuildFuzzinessQueryClauses(tt.queryStr, tt.fuzziness, tt.defaultFields)
+			assert.NoError(t, err)
+			assert.Equal(t, tt.wantClauseLen, len(clauses))
+			// Assert clause types
+			for i, clause := range clauses {
+				assert.Equal(t, tt.wantClauseTypes[i], clause.Operator, "clause %d type mismatch", i)
+			}
+		})
+	}
+}
+
+func TestBuildFuzzinessQueryClauses_InvalidFuzziness(t *testing.T) {
+	tests := []struct {
+		name      string
+		fuzziness int
+	}{
+		{name: "fuzziness -1", fuzziness: -1},
+		{name: "fuzziness 6", fuzziness: 6},
+		{name: "fuzziness 100", fuzziness: 100},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			clauses, err := BuildFuzzinessQueryClauses("mysql", tt.fuzziness, []string{"title"})
+			assert.Error(t, err)
+			assert.Nil(t, clauses)
+			assert.Contains(t, err.Error(), "invalid fuzziness value")
+		})
+	}
+}
+
+func TestBuildFuzzinessQueryClauses_EmptyQuery(t *testing.T) {
+	// Empty query string with default fields still generates clauses
+	clauses, err := BuildFuzzinessQueryClauses("", 3, []string{"title"})
+	assert.NoError(t, err)
+	// fuzziness 3 generates 3 clauses per field (Match, Prefix, MatchPhrase)
+	assert.Equal(t, 3, len(clauses))
+	// Assert clause types
+	expectedTypes := []QueryType{QueryMatch, QueryPrefix, QueryMatchPhrase}
+	for i, clause := range clauses {
+		assert.Equal(t, expectedTypes[i], clause.Operator, "clause %d type mismatch", i)
+	}
+}
+
+func TestBuildFuzzinessQueryClauses_EmptyQueryNoDefaultFields(t *testing.T) {
+	// Empty query string with no default fields returns empty clauses
+	clauses, err := BuildFuzzinessQueryClauses("", 3, []string{})
+	assert.NoError(t, err)
+	assert.Equal(t, 0, len(clauses))
+}

docs/content.en/docs/release-notes/_index.md

@@ -13,6 +13,7 @@ Information about release notes of INFINI Framework is provided here.
 ### 🚀 Features  
 - feat: support team-based scope for sharing services #258
 - feat: add semantic, hybrid, and nested query support #265
+- feat: extract BuildFuzzinessQueryClauses as public API #266
 
 ### 🐛 Bug fix  
 ### ✈️ Improvements