syntax: datetime helpers

atproto/syntax/datetime.go

···
 	"fmt"
 	"regexp"
 	"strings"
+	"time"
+)
+
+const (
+	// Prefered atproto Datetime string syntax, for use with [time.Format].
+	//
+	// Note that *parsing* syntax is more flexible.
+	AtprotoDatetimeLayout = "2006-01-02T15:04:05.999Z"
 )
 
 // Represents the a Datetime in string format, as would pass Lexicon syntax validation: the intersection of RFC-3339 and ISO-8601 syntax.
···
 		return "", fmt.Errorf("Datetime can't use '-00:00' for UTC timezone, must use '+00:00', per ISO-8601")
 	}
 	return Datetime(raw), nil
+}
+
+// Parses a string to a golang time.Time in a single step.
+func ParseDatetimeTime(raw string) (time.Time, error) {
+	var zero time.Time
+	d, err := ParseDatetime(raw)
+	if err != nil {
+		return zero, err
+	}
+	return d.Time()
+}
+
+// Parses the Datetime string in to a golang time.Time.
+//
+// There are a small number of strings which will pass initial syntax validation but fail when actually parsing, so this function can return an error. Use [ParseDatetimeTime] to fully parse in a single function call.
+func (d Datetime) Time() (time.Time, error) {
+	return time.Parse(time.RFC3339Nano, d.String())
+}
+
+// Creates a new valid Datetime string matching the current time, in prefered syntax.
+func DatetimeNow() Datetime {
+	t := time.Now().UTC()
+	return Datetime(t.Format(AtprotoDatetimeLayout))
 }
 
 func (d Datetime) String() string {

atproto/syntax/datetime_test.go

···
 	"github.com/stretchr/testify/assert"
 )
 
-func TestInteropDatetimesValid(t *testing.T) {
+func TestInteropDatetimeValid(t *testing.T) {
 	assert := assert.New(t)
 	file, err := os.Open("testdata/datetime_syntax_valid.txt")
 	assert.NoError(err)
···
 		if len(line) == 0 || line[0] == '#' {
 			continue
 		}
-		_, err := ParseDatetime(line)
+		_, err := ParseDatetimeTime(line)
 		if err != nil {
 			fmt.Println("GOOD: " + line)
 		}
···
 	assert.NoError(scanner.Err())
 }
 
-func TestInteropDatetimesInvalid(t *testing.T) {
+func TestInteropDatetimeInvalid(t *testing.T) {
 	assert := assert.New(t)
 	file, err := os.Open("testdata/datetime_syntax_invalid.txt")
 	assert.NoError(err)
···
 	}
 	assert.NoError(scanner.Err())
 }
+
+func TestInteropDatetimeTimeInvalid(t *testing.T) {
+	assert := assert.New(t)
+	file, err := os.Open("testdata/datetime_parse_invalid.txt")
+	assert.NoError(err)
+	defer file.Close()
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if len(line) == 0 || line[0] == '#' {
+			continue
+		}
+		_, err := ParseDatetimeTime(line)
+		if err == nil {
+			fmt.Println("BAD: " + line)
+		}
+		assert.Error(err)
+	}
+	assert.NoError(scanner.Err())
+}
+
+func TestInteropDatetimeNow(t *testing.T) {
+	assert := assert.New(t)
+
+	dt := DatetimeNow()
+	_, err := ParseDatetimeTime(dt.String())
+	assert.NoError(err)
+}

atproto/syntax/testdata/datetime_parse_invalid.txt

···
+# superficial syntax parses ok, but are not valid datetimes for semantic reasons (eg, "month zero")
+#1985-00-12T23:20:50.123Z
+#1985-04-00T23:20:50.123Z
+#1985-13-12T23:20:50.123Z
+#1985-04-12T25:20:50.123Z
+#1985-04-12T23:61:50.123Z
+#1985-04-12T23:20:61.123Z

atproto/syntax/testdata/datetime_syntax_invalid.txt

···
 1985-04-12T23:20:50.123Z 
 1985-04-12T 23:20:50.123Z
 
-# TODO: full parse to validate?
-#1985-00-12T23:20:50.123Z
-#1985-04-00T23:20:50.123Z
-#1985-13-12T23:20:50.123Z
-#1985-04-12T25:20:50.123Z
-#1985-04-12T23:61:50.123Z
-#1985-04-12T23:20:61.123Z
-
 # not enough zero padding
 1985-4-12T23:20:50.123Z
 1985-04-2T23:20:50.123Z

atproto/syntax/testdata/datetime_syntax_valid.txt

···
 0985-04-12T23:20:50.123-07:00
 1985-04-12T23:20:50.123-07:00
 0123-01-01T00:00:00.000Z
+
+# various precisions, up through at least 12 digits
[phone]T23:20:50.1Z
[phone]T23:20:50.12Z
[phone]T23:20:50.123Z
[phone]T23:20:50.1234Z
[phone]T23:20:50.12345Z
[phone]T23:20:50.123456Z
[phone]T23:20:50.1234567Z
[phone]T23:20:50.12345678Z
[phone]T23:20:50.123456789Z
[phone]T23:20:50.1234567890Z
[phone]T23:20:50.12345678901Z
[phone]T23:20:50.123456789012Z