feat: add Floor/Ceil and TimeRange for time-based ID queries

floor_ceil_test.go

@@ -0,0 +1,136 @@
+package typeid
+
+import (
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+type testUserPrefix struct{}
+
+func (testUserPrefix) Prefix() string { return "user" }
+
+type testOrgPrefix struct{}
+
+func (testOrgPrefix) Prefix() string { return "org" }
+
+func TestFloorUUID(t *testing.T) {
+	now := time.Now()
+	floor := floorUUID[testUserPrefix](now)
+	u := floor.UUID()
+
+	if u.Version() != 7 {
+		t.Fatalf("version = %d, want 7", u.Version())
+	}
+	if u.Variant() != uuid.RFC4122 {
+		t.Fatalf("variant = %d, want RFC4122", u.Variant())
+	}
+
+	// Any UUIDv7 generated after now must be >= floor.
+	for range 100 {
+		id, err := NewUUID[testUserPrefix]()
+		if err != nil {
+			t.Fatal(err)
+		}
+		if id.UUID().String() < u.String() {
+			t.Fatalf("NewUUID %s < floor %s", id.UUID(), u)
+		}
+	}
+}
+
+func TestCeilUUID(t *testing.T) {
+	now := time.Now()
+	ceil := ceilUUID[testUserPrefix](now)
+	floor := floorUUID[testUserPrefix](now)
+
+	u := ceil.UUID()
+	if u.Version() != 7 {
+		t.Fatalf("version = %d, want 7", u.Version())
+	}
+	if u.Variant() != uuid.RFC4122 {
+		t.Fatalf("variant = %d, want RFC4122", u.Variant())
+	}
+	if ceil.UUID().String() < floor.UUID().String() {
+		t.Fatalf("ceil %s < floor %s", ceil.UUID(), floor.UUID())
+	}
+}
+
+func TestFloorCeilUUID_Bracket(t *testing.T) {
+	id, err := NewUUID[testUserPrefix]()
+	if err != nil {
+		t.Fatal(err)
+	}
+	u := id.UUID()
+	ts := id.GetTime()
+
+	floor := floorUUID[testUserPrefix](ts)
+	ceil := ceilUUID[testUserPrefix](ts)
+
+	if floor.UUID().String() > u.String() {
+		t.Fatalf("floor %s > id %s", floor.UUID(), u)
+	}
+	if ceil.UUID().String() < u.String() {
+		t.Fatalf("ceil %s < id %s", ceil.UUID(), u)
+	}
+}
+
+func TestFloorUUID_TimestampRoundTrip(t *testing.T) {
+	ts := time.Date(2026, 3, 27, 12, 0, 0, 0, time.UTC)
+	floor := floorUUID[testUserPrefix](ts)
+	if got := floor.GetTime(); got.UnixMilli() != ts.UnixMilli() {
+		t.Fatalf("GetTime() = %v, want %v", got, ts)
+	}
+}
+
+func TestFloorInt64(t *testing.T) {
+	now := time.Now()
+	floor := floorInt64[testOrgPrefix](now)
+
+	for range 100 {
+		id, err := NewInt64[testOrgPrefix]()
+		if err != nil {
+			t.Fatal(err)
+		}
+		if id.Int64() < floor.Int64() {
+			t.Fatalf("NewInt64 %d < floor %d", id.Int64(), floor.Int64())
+		}
+	}
+}
+
+func TestCeilInt64(t *testing.T) {
+	now := time.Now()
+	ceil := ceilInt64[testOrgPrefix](now)
+	floor := floorInt64[testOrgPrefix](now)
+
+	if ceil.Int64() < floor.Int64() {
+		t.Fatalf("ceil %d < floor %d", ceil.Int64(), floor.Int64())
+	}
+}
+
+func TestFloorCeilInt64_Bracket(t *testing.T) {
+	id, err := NewInt64[testOrgPrefix]()
+	if err != nil {
+		t.Fatal(err)
+	}
+	v := id.Int64()
+	ts := id.GetTime()
+
+	floor := floorInt64[testOrgPrefix](ts)
+	ceil := ceilInt64[testOrgPrefix](ts)
+
+	if floor.Int64() > v {
+		t.Fatalf("floor %d > id %d", floor.Int64(), v)
+	}
+	if ceil.Int64() < v {
+		t.Fatalf("ceil %d < id %d", ceil.Int64(), v)
+	}
+}
+
+func TestInt64_GetTime(t *testing.T) {
+	ts := time.Date(2026, 3, 27, 12, 0, 0, 0, time.UTC)
+	floor := floorInt64[testOrgPrefix](ts)
+	if got := floor.GetTime(); got.UnixMilli() != ts.UnixMilli() {
+		t.Fatalf("GetTime() = %v, want %v", got, ts)
+	}
+}

int64.go

@@ -46,6 +46,7 @@ type Int64[P Prefixer] struct {
 	val int64
 }
 
+// NewInt64 generates a fresh time-ordered identifier with the given prefix.
 func NewInt64[P Prefixer]() (Int64[P], error) {
 	ms := time.Now().UnixMilli()
 
@@ -58,13 +59,15 @@ func NewInt64[P Prefixer]() (Int64[P], error) {
 	return Int64[P]{val: (ms << randomBits) | r}, nil
 }
 
+// Int64From wraps an existing int64 value, returning an error if it is not positive.
 func Int64From[P Prefixer](v int64) (Int64[P], error) {
 	if v <= 0 {
 		return Int64[P]{}, ErrNonPositiveInt
 	}
 	return Int64[P]{val: v}, nil
 }
 
+// ParseInt64 decodes a "prefix_<base32>" string into a typed Int64.
 func ParseInt64[P Prefixer](s string) (Int64[P], error) {
 	suffix, err := splitTypeid[P](s, int64SuffixLen)
 	if err != nil {
@@ -108,6 +111,23 @@ func (id Int64[P]) Value() (driver.Value, error) {
 	return id.val, nil
 }
 
+// GetTime extracts the millisecond-precision creation timestamp from the ID.
+func (id Int64[P]) GetTime() time.Time {
+	return time.UnixMilli(id.val >> randomBits)
+}
+
+// floorInt64 returns the lowest possible Int64[P] for timestamp t.
+// All 15 random bits are zero.
+func floorInt64[P Prefixer](t time.Time) Int64[P] {
+	return Int64[P]{val: t.UnixMilli() << randomBits}
+}
+
+// ceilInt64 returns the highest possible Int64[P] for timestamp t.
+// All 15 random bits are one.
+func ceilInt64[P Prefixer](t time.Time) Int64[P] {
+	return Int64[P]{val: t.UnixMilli()<<randomBits | 0x7FFF}
+}
+
 func (id *Int64[P]) Scan(src any) error {
 	var v int64
 	switch sv := src.(type) {

timerange.go

@@ -0,0 +1,83 @@
+package typeid
+
+import (
+	"database/sql/driver"
+	"fmt"
+	"time"
+)
+
+// TimeRange holds optional floor/ceil bounds for time-based ID range queries
+// against a primary key column. It satisfies squirrel.Sqlizer structurally
+// via [TimeRange.ToSql], so it can be passed directly to squirrel.Where
+// without importing squirrel in this package.
+//
+// Construct via [UUIDRange] or [Int64Range].
+type TimeRange struct {
+	column string
+	floor  driver.Valuer
+	ceil   driver.Valuer
+}
+
+// UUIDRange builds a [TimeRange] that brackets column with [FloorUUID] / [CeilUUID].
+// Nil since or until leaves that side unbounded.
+func UUIDRange[P Prefixer](column string, since, until *time.Time) TimeRange {
+	r := TimeRange{column: column}
+	if since != nil {
+		r.floor = floorUUID[P](*since)
+	}
+	if until != nil {
+		r.ceil = ceilUUID[P](*until)
+	}
+	return r
+}
+
+// Int64Range builds a [TimeRange] that brackets column with [FloorInt64] / [CeilInt64].
+// Nil since or until leaves that side unbounded.
+func Int64Range[P Prefixer](column string, since, until *time.Time) TimeRange {
+	r := TimeRange{column: column}
+	if since != nil {
+		r.floor = floorInt64[P](*since)
+	}
+	if until != nil {
+		r.ceil = ceilInt64[P](*until)
+	}
+	return r
+}
+
+// Floor returns the lower-bound ID and true, or (nil, false) if unbounded.
+func (r TimeRange) Floor() (driver.Valuer, bool) { return r.floor, r.floor != nil }
+
+// Ceil returns the upper-bound ID and true, or (nil, false) if unbounded.
+func (r TimeRange) Ceil() (driver.Valuer, bool) { return r.ceil, r.ceil != nil }
+
+// ToSql emits a SQL predicate and bind args for the range.
+// Returns "column BETWEEN ? AND ?", "column >= ?", "column <= ?",
+// or "1=1" depending on which bounds are set.
+func (r TimeRange) ToSql() (string, []any, error) {
+	switch {
+	case r.floor != nil && r.ceil != nil:
+		fv, err := r.floor.Value()
+		if err != nil {
+			return "", nil, fmt.Errorf("typeid: floor value: %w", err)
+		}
+		cv, err := r.ceil.Value()
+		if err != nil {
+			return "", nil, fmt.Errorf("typeid: ceil value: %w", err)
+		}
+		return r.column + " BETWEEN ? AND ?", []any{fv, cv}, nil
+	case r.floor != nil:
+		fv, err := r.floor.Value()
+		if err != nil {
+			return "", nil, fmt.Errorf("typeid: floor value: %w", err)
+		}
+		return r.column + " >= ?", []any{fv}, nil
+	case r.ceil != nil:
+		cv, err := r.ceil.Value()
+		if err != nil {
+			return "", nil, fmt.Errorf("typeid: ceil value: %w", err)
+		}
+		return r.column + " <= ?", []any{cv}, nil
+	default:
+		return "1=1", nil, nil
+	}
+}

timerange_test.go

@@ -0,0 +1,129 @@
+package typeid_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/go-chi/typeid"
+)
+
+func TestUUID_GetTime(t *testing.T) {
+	id, err := typeid.NewUUID[userPrefix]()
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := id.GetTime()
+	if got.IsZero() {
+		t.Fatal("GetTime() returned zero")
+	}
+	if time.Since(got) > time.Second {
+		t.Fatalf("GetTime() = %v, too far from now", got)
+	}
+}
+
+func TestInt64_GetTime(t *testing.T) {
+	id, err := typeid.NewInt64[orgPrefix]()
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := id.GetTime()
+	if got.IsZero() {
+		t.Fatal("GetTime() returned zero")
+	}
+	if time.Since(got) > time.Second {
+		t.Fatalf("GetTime() = %v, too far from now", got)
+	}
+}
+
+func TestTimeRange_ToSql_BothSet(t *testing.T) {
+	since := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+	until := time.Date(2026, 3, 27, 0, 0, 0, 0, time.UTC)
+	r := typeid.UUIDRange[userPrefix]("id", &since, &until)
+
+	sql, args, err := r.ToSql()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sql != "id BETWEEN ? AND ?" {
+		t.Fatalf("sql = %q", sql)
+	}
+	if len(args) != 2 {
+		t.Fatalf("args len = %d, want 2", len(args))
+	}
+}
+
+func TestTimeRange_ToSql_SinceOnly(t *testing.T) {
+	since := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+	r := typeid.UUIDRange[userPrefix]("id", &since, nil)
+
+	sql, args, err := r.ToSql()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sql != "id >= ?" {
+		t.Fatalf("sql = %q", sql)
+	}
+	if len(args) != 1 {
+		t.Fatalf("args len = %d, want 1", len(args))
+	}
+}
+
+func TestTimeRange_ToSql_UntilOnly(t *testing.T) {
+	until := time.Date(2026, 3, 27, 0, 0, 0, 0, time.UTC)
+	r := typeid.UUIDRange[userPrefix]("id", nil, &until)
+
+	sql, args, err := r.ToSql()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sql != "id <= ?" {
+		t.Fatalf("sql = %q", sql)
+	}
+	if len(args) != 1 {
+		t.Fatalf("args len = %d, want 1", len(args))
+	}
+}
+
+func TestTimeRange_ToSql_Neither(t *testing.T) {
+	r := typeid.UUIDRange[userPrefix]("id", nil, nil)
+
+	sql, args, err := r.ToSql()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sql != "1=1" {
+		t.Fatalf("sql = %q", sql)
+	}
+	if len(args) != 0 {
+		t.Fatalf("args len = %d, want 0", len(args))
+	}
+}
+
+func TestTimeRange_ToSql_Int64(t *testing.T) {
+	since := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+	until := time.Date(2026, 3, 27, 0, 0, 0, 0, time.UTC)
+	r := typeid.Int64Range[orgPrefix]("id", &since, &until)
+
+	sql, args, err := r.ToSql()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sql != "id BETWEEN ? AND ?" {
+		t.Fatalf("sql = %q", sql)
+	}
+	if len(args) != 2 {
+		t.Fatalf("args len = %d, want 2", len(args))
+	}
+}
+
+func TestTimeRange_FloorCeil_Accessors(t *testing.T) {
+	since := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+	r := typeid.UUIDRange[userPrefix]("id", &since, nil)
+
+	if _, ok := r.Floor(); !ok {
+		t.Fatal("Floor() returned false")
+	}
+	if _, ok := r.Ceil(); ok {
+		t.Fatal("Ceil() returned true for nil until")
+	}
+}