feat: Add ListBaselineStatusCount to retrieve cumulative baseline feature counts

This PR introduces the `ListBaselineStatusCount` function and its associated helper functions to retrieve a cumulative count of baseline features over time.

The `ListBaselineStatusCount` function works similarly to `ListBrowserFeatureCountMetric` by:

1. Calculating an initial cumulative count of baseline features up to the specified `startAt` date.
2. Retrieving subsequent baseline feature counts within the specified date range (`startAt` to `endAt`).
3. Accumulating these counts to provide a cumulative view of baseline feature adoption over time.

Currently, the function only supports retrieving counts based on the `LowDate` field in the `FeatureBaselineStatus` table. However, support for `HighDate` can be easily added in the future by expanding the `BaselineDateType` enum and updating the query construction logic.

This functionality is useful for tracking the overall adoption of baseline features and understanding how the baseline status of features changes over time.

Author: jcscottiii

lib/gcpspanner/baseline_status_count.go

@@ -0,0 +1,240 @@
+package gcpspanner
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"cloud.google.com/go/spanner"
+	"google.golang.org/api/iterator"
+)
+
+// BaselineDateType is an enum representing the type of date to use for baseline counts.
+type BaselineDateType string
+
+const (
+	// BaselineDateTypeLow uses the LowDate from FeatureBaselineStatus.
+	BaselineDateTypeLow BaselineDateType = "low"
+)
+
+// BaselineStatusCountMetric represents a single data point in the baseline status count time series.
+type BaselineStatusCountMetric struct {
+	Date        time.Time `spanner:"Date"`
+	StatusCount int64     `spanner:"StatusCount"`
+}
+
+// BaselineStatusCountResultPage is a page of results for the baseline status count query.
+type BaselineStatusCountResultPage struct {
+	NextPageToken *string
+	Metrics       []BaselineStatusCountMetric
+}
+
+// baselineStatusCountCursor is used for pagination.
+type baselineStatusCountCursor struct {
+	LastDate        time.Time `json:"last_date"`
+	LastStatusCount int64     `json:"last_status_count"`
+}
+
+// decodeBaselineStatusCountCursor decodes a cursor string into a baselineStatusCountCursor.
+func decodeBaselineStatusCountCursor(cursor string) (*baselineStatusCountCursor, error) {
+	return decodeCursor[baselineStatusCountCursor](cursor)
+}
+
+// encodeBaselineStatusCountCursor encodes a baselineStatusCountCursor into a cursor string.
+func encodeBaselineStatusCountCursor(lastDate time.Time, lastStatusCount int64) string {
+	return encodeCursor(baselineStatusCountCursor{
+		LastDate:        lastDate,
+		LastStatusCount: lastStatusCount,
+	})
+}
+
+type fbsColumn string
+
+const fbsColumnLowDate fbsColumn = "fbs.LowDate"
+
+// ListBaselineStatusCount retrieves a cumulative count of baseline features over time.
+func (c *Client) ListBaselineStatusCount(
+	ctx context.Context,
+	dateType BaselineDateType,
+	startAt time.Time,
+	endAt time.Time,
+	pageSize int,
+	pageToken *string,
+) (*BaselineStatusCountResultPage, error) {
+	var parsedToken *baselineStatusCountCursor
+	var err error
+	if pageToken != nil {
+		parsedToken, err = decodeBaselineStatusCountCursor(*pageToken)
+		if err != nil {
+			return nil, errors.Join(ErrInternalQueryFailure, err)
+		}
+	}
+
+	txn := c.ReadOnlyTransaction()
+	defer txn.Close()
+
+	// 1. Validate dateType
+	switch dateType {
+	case BaselineDateTypeLow:
+		break
+	default:
+		return nil, errors.Join(ErrInternalQueryFailure, fmt.Errorf("invalid BaselineDateType: %s", dateType))
+	}
+
+	// 2. Get excluded feature IDs
+	excludedFeatureIDs, err := c.getFeatureIDsForEachExcludedFeatureKey(ctx, txn)
+	if err != nil {
+		return nil, err
+	}
+
+	// 3. Calculate initial cumulative count
+	cumulativeCount, err := c.getInitialBaselineStatusCount(
+		ctx, txn, parsedToken, startAt, excludedFeatureIDs, dateType)
+	if err != nil {
+		return nil, errors.Join(ErrInternalQueryFailure, err)
+	}
+
+	// 4. Process results and update cumulative count
+	stmt := createListBaselineStatusCountStatement(dateType, startAt, endAt, pageSize, parsedToken, excludedFeatureIDs)
+
+	iter := txn.Query(ctx, stmt)
+	defer iter.Stop()
+
+	var metrics []BaselineStatusCountMetric
+	for {
+		row, err := iter.Next()
+		if errors.Is(err, iterator.Done) {
+			break
+		}
+		if err != nil {
+			return nil, errors.Join(ErrInternalQueryFailure, err)
+		}
+
+		var metric BaselineStatusCountMetric
+		if err := row.ToStruct(&metric); err != nil {
+			return nil, err
+		}
+
+		cumulativeCount += metric.StatusCount
+		metric.StatusCount = cumulativeCount
+		metrics = append(metrics, metric)
+	}
+
+	var newCursor *string
+	if len(metrics) == pageSize {
+		lastMetric := metrics[len(metrics)-1]
+		generatedCursor := encodeBaselineStatusCountCursor(lastMetric.Date, lastMetric.StatusCount)
+		newCursor = &generatedCursor
+	}
+
+	return &BaselineStatusCountResultPage{
+		NextPageToken: newCursor,
+		Metrics:       metrics,
+	}, nil
+}
+
+// getInitialBaselineStatusCount calculates the initial cumulative count for the first page.
+func (c *Client) getInitialBaselineStatusCount(
+	ctx context.Context,
+	txn *spanner.ReadOnlyTransaction,
+	parsedToken *baselineStatusCountCursor,
+	startAt time.Time,
+	excludedFeatureIDs []string,
+	dateType BaselineDateType,
+) (int64, error) {
+	if parsedToken != nil {
+		return parsedToken.LastStatusCount, nil
+	}
+
+	params := map[string]interface{}{
+		"startAt": startAt,
+	}
+
+	var excludedFeatureFilter string
+	if len(excludedFeatureIDs) > 0 {
+		excludedFeatureFilter = `
+				AND fbs.WebFeatureID NOT IN UNNEST(@excludedFeatureIDs)`
+		params["excludedFeatureIDs"] = excludedFeatureIDs
+	}
+
+	// Construct the query based on dateType
+	var dateField string
+	switch dateType {
+	case BaselineDateTypeLow:
+		dateField = string(fbsColumnLowDate)
+	}
+
+	var initialCount int64
+	stmt := spanner.Statement{
+		SQL: fmt.Sprintf(`
+				SELECT COALESCE(SUM(daily_status_count), 0)
+				FROM (
+						SELECT COUNT(fbs.WebFeatureID) AS daily_status_count
+						FROM FeatureBaselineStatus fbs
+						WHERE %s < @startAt %s
+						GROUP BY %s
+				)`, dateField, excludedFeatureFilter, dateField),
+		Params: params,
+	}
+
+	err := txn.Query(ctx, stmt).Do(func(r *spanner.Row) error {
+		return r.Column(0, &initialCount)
+	})
+
+	return initialCount, err
+}
+
+// createListBaselineStatusCountStatement creates the Spanner statement for the main query.
+func createListBaselineStatusCountStatement(
+	dateType BaselineDateType,
+	startAt time.Time,
+	endAt time.Time,
+	pageSize int,
+	pageToken *baselineStatusCountCursor,
+	excludedFeatureIDs []string,
+) spanner.Statement {
+	params := map[string]interface{}{
+		"startAt":  startAt,
+		"endAt":    endAt,
+		"pageSize": pageSize,
+	}
+
+	var pageFilter string
+	if pageToken != nil {
+		var dateField string
+		switch dateType {
+		case BaselineDateTypeLow:
+			dateField = string(fbsColumnLowDate)
+		}
+		pageFilter = fmt.Sprintf(`AND %s > @lastDate`, dateField)
+		params["lastDate"] = pageToken.LastDate
+	}
+
+	var excludedFeatureFilter string
+	if len(excludedFeatureIDs) > 0 {
+		excludedFeatureFilter = `AND fbs.WebFeatureID NOT IN UNNEST(@excludedFeatureIDs)`
+		params["excludedFeatureIDs"] = excludedFeatureIDs
+	}
+
+	// Construct the query based on dateType
+	var dateField string
+	switch dateType {
+	case BaselineDateTypeLow:
+		dateField = string(fbsColumnLowDate)
+	}
+
+	stmt := spanner.Statement{
+		SQL: fmt.Sprintf(`
+				SELECT %s AS Date, COUNT(fbs.WebFeatureID) AS StatusCount
+				FROM FeatureBaselineStatus fbs
+				WHERE %s >= @startAt AND %s < @endAt %s %s
+				GROUP BY %s
+				ORDER BY %s
+				LIMIT @pageSize`,
+			dateField, dateField, dateField, pageFilter, excludedFeatureFilter, dateField, dateField),
+		Params: params,
+	}
+
+	return stmt
+}