feat: add Stat method (#127)

ferhatelmas · web-flow · commit 8111aec69ca1 · 2025-10-10T00:13:56.000+02:00
diff --git a/flock.go b/flock.go
@@ -125,6 +125,22 @@ func (f *Flock) RLocked() bool {
 	return f.r
 }
 
+// Stat returns the FileInfo structure describing the lock file.
+// If the lock file does not exist or cannot be accessed, an error is returned.
+//
+// This can be used to check the modification time of the lock file,
+// which is useful for detecting stale locks.
+func (f *Flock) Stat() (fs.FileInfo, error) {
+	f.m.RLock()
+	defer f.m.RUnlock()
+
+	if f.fh != nil {
+		return f.fh.Stat()
+	}
+
+	return os.Stat(f.path)
+}
+
 func (f *Flock) String() string {
 	return f.path
 }
diff --git a/flock_test.go b/flock_test.go
@@ -313,3 +313,36 @@ func (s *TestSuite) TestFlock_RLock() {
 	s.False(gf.Locked())
 	s.True(gf.RLocked())
 }
+
+func (s *TestSuite) TestFlock_Stat() {
+	// Test Stat when file doesn't exist yet (for non-directory case)
+	if !s.dir {
+		_, err := s.flock.Stat()
+		s.True(os.IsNotExist(err))
+	}
+
+	// Create the lock file
+	locked, err := s.flock.TryLock()
+	s.Require().NoError(err)
+	s.True(locked)
+
+	// Test Stat after lock is acquired
+	info, err := s.flock.Stat()
+	s.Require().NoError(err)
+	s.NotNil(info)
+
+	// Check modification time is recent
+	modTime := info.ModTime()
+	s.WithinDuration(time.Now(), modTime, 1*time.Second)
+
+	// Unlock and verify Stat still works (file persists)
+	err = s.flock.Unlock()
+	s.Require().NoError(err)
+
+	info, err = s.flock.Stat()
+	s.Require().NoError(err)
+	s.NotNil(info)
+
+	// The modification time should be approximately the same as before
+	s.WithinDuration(modTime, info.ModTime(), 100*time.Millisecond)
+}
