feat: add RestoreByID and export timestamp interfaces

- Add RestoreByID method that clears DeletedAt by passing zero time
- Export HasSetCreatedAt, HasSetUpdatedAt, HasSetDeletedAt interfaces
  with godoc explaining the contract for each lifecycle hook
- Update SetDeletedAt implementations to treat zero time as restore (nil)

Author: klaidliadon

table.go

@@ -30,18 +30,34 @@ type Table[T any, P Record[T, I], I ID] struct {
 	Paginator Paginator[P]
 }
 
-// helpers for setting timestamp fields
-type (
-	hasSetCreatedAt interface {
-		SetCreatedAt(time.Time)
-	}
-	hasSetUpdatedAt interface {
-		SetUpdatedAt(time.Time)
-	}
-	hasSetDeletedAt interface {
-		SetDeletedAt(time.Time)
-	}
-)
+// HasSetCreatedAt is implemented by records that track creation time.
+// Insert will automatically call SetCreatedAt with the current UTC time.
+type HasSetCreatedAt interface {
+	SetCreatedAt(time.Time)
+}
+
+// HasSetUpdatedAt is implemented by records that track update time.
+// Insert, Update, and Save will automatically call SetUpdatedAt with the current UTC time.
+type HasSetUpdatedAt interface {
+	SetUpdatedAt(time.Time)
+}
+
+// HasSetDeletedAt is implemented by records that support soft delete.
+// DeleteByID will call SetDeletedAt with the current UTC time to soft-delete,
+// and RestoreByID will call SetDeletedAt with a zero time.Time{} to restore.
+//
+// Implementations should treat a zero time as a restore (clear the timestamp):
+//
+//	func (r *MyRecord) SetDeletedAt(t time.Time) {
+//		if t.IsZero() {
+//			r.DeletedAt = nil // restore: clear the timestamp
+//			return
+//		}
+//		r.DeletedAt = &t // soft delete: set the timestamp
+//	}
+type HasSetDeletedAt interface {
+	SetDeletedAt(time.Time)
+}
 
 // Insert inserts one or more records. Sets CreatedAt and UpdatedAt timestamps if available.
 // Records are returned with their generated fields populated via RETURNING *.
@@ -66,10 +82,10 @@ func (t *Table[T, P, I]) insertOne(ctx context.Context, record P) error {
 	}
 
 	now := time.Now().UTC()
-	if row, ok := any(record).(hasSetCreatedAt); ok {
+	if row, ok := any(record).(HasSetCreatedAt); ok {
 		row.SetCreatedAt(now)
 	}
-	if row, ok := any(record).(hasSetUpdatedAt); ok {
+	if row, ok := any(record).(HasSetUpdatedAt); ok {
 		row.SetUpdatedAt(now)
 	}
 
@@ -97,10 +113,10 @@ func (t *Table[T, P, I]) insertAll(ctx context.Context, records []P) error {
 			return fmt.Errorf("validate record: %w", err)
 		}
 
-		if row, ok := any(r).(hasSetCreatedAt); ok {
+		if row, ok := any(r).(HasSetCreatedAt); ok {
 			row.SetCreatedAt(now)
 		}
-		if row, ok := any(r).(hasSetUpdatedAt); ok {
+		if row, ok := any(r).(HasSetUpdatedAt); ok {
 			row.SetUpdatedAt(now)
 		}
 	}
@@ -152,7 +168,7 @@ func (t *Table[T, P, I]) updateOne(ctx context.Context, record P) error {
 		return fmt.Errorf("validate record: %w", err)
 	}
 
-	if row, ok := any(record).(hasSetUpdatedAt); ok {
+	if row, ok := any(record).(HasSetUpdatedAt); ok {
 		row.SetUpdatedAt(time.Now().UTC())
 	}
 
@@ -183,7 +199,7 @@ func (t *Table[T, P, I]) updateAll(ctx context.Context, records []P) error {
 			return fmt.Errorf("validate record: %w", err)
 		}
 
-		if row, ok := any(r).(hasSetUpdatedAt); ok {
+		if row, ok := any(r).(HasSetUpdatedAt); ok {
 			row.SetUpdatedAt(now)
 		}
 
@@ -223,7 +239,7 @@ func (t *Table[T, P, I]) saveOne(ctx context.Context, record P) error {
 		return fmt.Errorf("validate record: %w", err)
 	}
 
-	if row, ok := any(record).(hasSetUpdatedAt); ok {
+	if row, ok := any(record).(HasSetUpdatedAt); ok {
 		row.SetUpdatedAt(time.Now().UTC())
 	}
 
@@ -270,13 +286,13 @@ func (t *Table[T, P, I]) saveAll(ctx context.Context, records []P) error {
 			return fmt.Errorf("validate record: %w", err)
 		}
 
-		if row, ok := any(r).(hasSetUpdatedAt); ok {
+		if row, ok := any(r).(HasSetUpdatedAt); ok {
 			row.SetUpdatedAt(now)
 		}
 
 		var zero I
 		if r.GetID() == zero {
-			if row, ok := any(r).(hasSetCreatedAt); ok {
+			if row, ok := any(r).(HasSetCreatedAt); ok {
 				row.SetCreatedAt(now)
 			}
 
@@ -432,7 +448,7 @@ func (t *Table[T, P, I]) DeleteByID(ctx context.Context, id I) error {
 	}
 
 	// Soft delete.
-	if row, ok := any(record).(hasSetDeletedAt); ok {
+	if row, ok := any(record).(HasSetDeletedAt); ok {
 		row.SetDeletedAt(time.Now().UTC())
 		if err := t.Save(ctx, record); err != nil {
 			return fmt.Errorf("soft delete: %w", err)
@@ -444,6 +460,27 @@ func (t *Table[T, P, I]) DeleteByID(ctx context.Context, id I) error {
 	return t.HardDeleteByID(ctx, id)
 }
 
+// RestoreByID restores a soft-deleted record by ID by clearing its DeletedAt timestamp.
+// Returns an error if the record does not implement .SetDeletedAt().
+func (t *Table[T, P, I]) RestoreByID(ctx context.Context, id I) error {
+	record, err := t.GetByID(ctx, id)
+	if err != nil {
+		return fmt.Errorf("restore: %w", err)
+	}
+
+	row, ok := any(record).(HasSetDeletedAt)
+	if !ok {
+		return fmt.Errorf("restore: record does not support soft delete")
+	}
+
+	row.SetDeletedAt(time.Time{})
+	if err := t.Save(ctx, record); err != nil {
+		return fmt.Errorf("restore: %w", err)
+	}
+
+	return nil
+}
+
 // HardDeleteByID permanently deletes a record by ID.
 func (t *Table[T, P, I]) HardDeleteByID(ctx context.Context, id I) error {
 	q := t.SQL.Delete(t.Name).Where(sq.Eq{t.IDColumn: id})

tests/schema_test.go

@@ -40,7 +40,13 @@ type Article struct {
 
 func (a *Article) GetID() uint64            { return a.ID }
 func (a *Article) SetUpdatedAt(t time.Time) { a.UpdatedAt = t }
-func (a *Article) SetDeletedAt(t time.Time) { a.DeletedAt = &t }
+func (a *Article) SetDeletedAt(t time.Time) {
+	if t.IsZero() {
+		a.DeletedAt = nil
+		return
+	}
+	a.DeletedAt = &t
+}
 
 func (a *Article) Validate() error {
 	if a.Author == "" {
@@ -71,7 +77,13 @@ type Review struct {
 
 func (r *Review) GetID() uint64            { return r.ID }
 func (r *Review) SetUpdatedAt(t time.Time) { r.UpdatedAt = t }
-func (r *Review) SetDeletedAt(t time.Time) { r.DeletedAt = &t }
+func (r *Review) SetDeletedAt(t time.Time) {
+	if t.IsZero() {
+		r.DeletedAt = nil
+		return
+	}
+	r.DeletedAt = &t
+}
 
 func (r *Review) Validate() error {
 	if len(r.Comment) < 3 {

tests/table_test.go

@@ -182,6 +182,19 @@ func TestTable(t *testing.T) {
 			require.Equal(t, firstArticle.ID, article.ID, "DeletedAt should be set")
 			require.NotNil(t, article.DeletedAt, "DeletedAt should be set")
 
+			// Restore first article.
+			err = tx.Articles.RestoreByID(ctx, firstArticle.ID)
+			require.NoError(t, err, "RestoreByID failed")
+
+			// Check if article is restored.
+			article, err = tx.Articles.GetByID(ctx, firstArticle.ID)
+			require.NoError(t, err, "GetByID failed after restore")
+			require.Nil(t, article.DeletedAt, "DeletedAt should be nil after restore")
+
+			// Soft-delete again for the hard-delete test.
+			err = tx.Articles.DeleteByID(ctx, firstArticle.ID)
+			require.NoError(t, err, "DeleteByID failed")
+
 			// Hard-delete first article.
 			err = tx.Articles.HardDeleteByID(ctx, firstArticle.ID)
 			require.NoError(t, err, "HardDeleteByID failed")