feat(shortcuts): add context-based DB helper shortcuts (require ContextWithManager) (#502)

Add  implementing QueryContext, ExecContext, QueryListContext and
QueryList2Context. Document that the  parameter must be produced by
 (accessible via ). Ensure rows are
closed after reading; no behavioral changes to existing APIs.

Author: eatmoreapple

shortcuts.go

@@ -0,0 +1,64 @@
+/*
+Copyright 2025 eatmoreapple
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package juice
+
+import (
+	"context"
+	"database/sql"
+)
+
+// This file provides context-based database helper shortcuts.
+
+// QueryContext executes a query with the provided context and scans a single result into T.
+// (ctx must contain a Manager via ManagerFromContext)
+func QueryContext[T any](ctx context.Context, statement, param any) (result T, err error) {
+	manager := ManagerFromContext(ctx)
+	executor := NewGenericManager[T](manager).Object(statement)
+	return executor.QueryContext(ctx, param)
+}
+
+// ExecContext executes a statement that does not return rows and returns a sql.Result.
+// (ctx must contain a Manager via ManagerFromContext)
+func ExecContext(ctx context.Context, statement, param any) (result sql.Result, err error) {
+	manager := ManagerFromContext(ctx)
+	executor := NewGenericManager[any](manager).Object(statement)
+	return executor.ExecContext(ctx, param)
+}
+
+// QueryListContext executes a query and returns a slice of T. Rows are closed after reading.
+// (ctx must contain a Manager via ManagerFromContext)
+func QueryListContext[T any](ctx context.Context, statement, param any) (result []T, err error) {
+	manager := ManagerFromContext(ctx)
+	rows, err := manager.Object(statement).QueryContext(ctx, param)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = rows.Close() }()
+	return List[T](rows)
+}
+
+// QueryList2Context executes a query and returns a slice of pointers to T. Rows are closed after reading.
+// (ctx must contain a Manager via ManagerFromContext)
+func QueryList2Context[T any](ctx context.Context, statement, param any) (result []*T, err error) {
+	manager := ManagerFromContext(ctx)
+	rows, err := manager.Object(statement).QueryContext(ctx, param)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = rows.Close() }()
+	return List2[T](rows)
+}