From 887c97575578bd01bbfde33e63351831d9f8cb64 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Fri, 28 Aug 2026 14:10:47 +0200
Subject: [PATCH] deprecate Filter type

Make the filter implementation private and retain Filter as a deprecated
type alias for compatibility.

Direct construction of Filter was never useful because its zero value is not
usable, and NewFilter already returns the Sink interface consumed by callers.
Move the concurrency warning to NewFilter, which is now the documented
construction path.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 filter.go      | 21 +++++++++++++--------
 filter_test.go |  6 +++---
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/filter.go b/filter.go
index e6c0eb6..5cf8630 100644
--- a/filter.go
+++ b/filter.go
@@ -13,22 +13,27 @@ func (fn MatcherFunc) Match(event Event) bool {
 	return fn(event)
 }
 
-// Filter provides an event sink that sends only events that are accepted by a
-// Matcher. No methods on filter are goroutine safe.
-type Filter struct {
+// Filter is the concrete implementation returned by [NewFilter].
+//
+// Deprecated: Filter should not be constructed directly. Use [NewFilter] instead.
+type Filter = filter
+
+type filter struct {
 	dst     Sink
 	matcher Matcher
 	closed  bool
 }
 
-// NewFilter returns a new filter that will send to events to dst that return
-// true for Matcher.
+// NewFilter returns a new event sink that forwards only events accepted by
+// matcher to dst.
+//
+// The returned Sink's methods are not safe for concurrent use.
 func NewFilter(dst Sink, matcher Matcher) Sink {
-	return &Filter{dst: dst, matcher: matcher}
+	return &filter{dst: dst, matcher: matcher}
 }
 
 // Write an event to the filter.
-func (f *Filter) Write(event Event) error {
+func (f *filter) Write(event Event) error {
 	if f.closed {
 		return ErrSinkClosed
 	}
@@ -41,7 +46,7 @@ func (f *Filter) Write(event Event) error {
 }
 
 // Close the filter and allow no more events to pass through.
-func (f *Filter) Close() error {
+func (f *filter) Close() error {
 	// TODO(stevvooe): Not all sinks should have Close.
 	if f.closed {
 		return nil
diff --git a/filter_test.go b/filter_test.go
index 18ccd8a..e61d908 100644
--- a/filter_test.go
+++ b/filter_test.go
@@ -5,16 +5,16 @@ import "testing"
 func TestFilter(t *testing.T) {
 	const nevents = 100
 	ts := newTestSink(t, nevents/2)
-	filter := NewFilter(ts, MatcherFunc(func(event Event) bool {
+	f := NewFilter(ts, MatcherFunc(func(event Event) bool {
 		i, ok := event.(int)
 		return ok && i%2 == 0
 	}))
 
 	for i := range nevents {
-		if err := filter.Write(i); err != nil {
+		if err := f.Write(i); err != nil {
 			t.Fatalf("unexpected error writing event: %v", err)
 		}
 	}
 
-	checkClose(t, filter)
+	checkClose(t, f)
 }