fix: address CodeRabbit review — null handling, date formats, docs, tests (#14)

- default(): fall through to rhs when lhs is null (types.NullValue)
- parseTimestamp(): try RFC3339Nano, bare ISO date, US date, and named-month formats before erroring
- expressions.md: remove undeclared `now` variable from two examples
- data-transformations.md: add missing exists_one row to list-macros table
- data-transform-api-to-db.yaml: simplify to single-user fetch+insert (fixes broken batch param shape)
- functions_test.go: add null/fallback tests for default(), edge-case tests for flatten(), and new format tests for parseTimestamp()

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: michaelmcnees

examples/data-transform-api-to-db.yaml

@@ -1,23 +1,26 @@
 name: data-transform-api-to-db
 description: >
-  Fetches user data from an API, transforms each record using CEL
-  expressions to match a database schema, and inserts the normalized
-  records into Postgres. Demonstrates map(), obj(), toLower(), and
-  type coercion without requiring an AI model.
+  Fetches a user from an API, transforms the record using CEL expressions
+  to match a database schema, and inserts the normalized data into Postgres.
+  Demonstrates obj(), toLower(), and string functions without requiring
+  an AI model.
 
 steps:
-  - name: fetch-users
+  - name: fetch-user
     action: http/request
     timeout: "15s"
     params:
       method: GET
-      url: "https://jsonplaceholder.typicode.com/users"
+      url: "https://jsonplaceholder.typicode.com/users/1"
       headers:
         Accept: "application/json"
 
-  - name: store-users
+  - name: store-user
     action: postgres/query
     credential: app-db
     params:
       query: "INSERT INTO users (username, email, city) VALUES ($1, $2, $3)"
-      params: "{{ steps['fetch-users'].output.json.map(u, [u.username.toLower(), u.email.toLower(), u.address.city]) }}"
+      args:
+        - "{{ steps['fetch-user'].output.json.username.toLower() }}"
+        - "{{ steps['fetch-user'].output.json.email.toLower() }}"
+        - "{{ steps['fetch-user'].output.json.address.city }}"

internal/cel/functions.go

@@ -159,7 +159,7 @@ func (l *collectionLib) CompileOptions() []cel.EnvOption {
 				[]*cel.Type{cel.DynType, cel.DynType},
 				cel.DynType,
 				cel.BinaryBinding(func(lhs, rhs ref.Val) ref.Val {
-					if types.IsError(lhs) || types.IsUnknown(lhs) {
+					if types.IsError(lhs) || types.IsUnknown(lhs) || lhs == types.NullValue {
 						return rhs
 					}
 					return lhs
@@ -304,11 +304,20 @@ func (l *timeLib) CompileOptions() []cel.EnvOption {
 				cel.TimestampType,
 				cel.UnaryBinding(func(val ref.Val) ref.Val {
 					s := string(val.(types.String))
-					t, err := time.Parse(time.RFC3339, s)
-					if err != nil {
-						return types.NewErr("parseTimestamp: %v", err)
+					layouts := []string{
+						time.RFC3339,
+						time.RFC3339Nano,
+						"2006-01-02T15:04:05",
+						"2006-01-02",
+						"01/02/2006",
+						"Jan 2, 2006",
+					}
+					for _, layout := range layouts {
+						if t, err := time.Parse(layout, s); err == nil {
+							return types.Timestamp{Time: t}
+						}
 					}
-					return types.Timestamp{Time: t}
+					return types.NewErr("parseTimestamp: unable to parse %q (tried RFC3339, ISO 8601 date, and common formats)", s)
 				}),
 			),
 		),

internal/cel/functions_test.go

@@ -253,6 +253,8 @@ func TestFunc_Default(t *testing.T) {
 	}{
 		{"value exists returns value", `default("hello", "fallback")`, "hello"},
 		{"empty string returns empty string", `default("", "fallback")`, ""},
+		{"null returns fallback", `default(null, "fallback")`, "fallback"},
+		{"non-null int unchanged", `default(42, 0)`, int64(42)},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -276,6 +278,11 @@ func TestFunc_Flatten(t *testing.T) {
 			expr: `flatten([[1, 2], [3, 4], [5]])`,
 			want: []any{int64(1), int64(2), int64(3), int64(4), int64(5)},
 		},
+		{
+			name: "mixed nested and non-nested",
+			expr: `flatten([[1], [3, 4]])`,
+			want: []any{int64(1), int64(3), int64(4)},
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -284,6 +291,20 @@ func TestFunc_Flatten(t *testing.T) {
 			assert.Equal(t, tt.want, result)
 		})
 	}
+
+	// Empty list: flatten([]) — result may be nil or empty slice.
+	t.Run("empty list", func(t *testing.T) {
+		ctx := newTestContext()
+		ctx.Inputs["empty"] = []any{}
+		result, err := eval.Eval(`flatten(inputs.empty)`, ctx)
+		require.NoError(t, err)
+		// CEL may return nil or an empty slice for an empty list; both are acceptable.
+		if result != nil {
+			list, ok := result.([]any)
+			require.True(t, ok, "expected []any, got %T", result)
+			assert.Empty(t, list)
+		}
+	})
 }
 
 // Task 7: jsonEncode and jsonDecode
@@ -364,6 +385,9 @@ func TestFunc_Timestamp(t *testing.T) {
 		{"iso8601", `parseTimestamp("2024-01-15T00:00:00Z")`, false},
 		{"with_offset", `parseTimestamp("2024-06-01T12:30:00+05:30")`, false},
 		{"invalid", `parseTimestamp("not-a-date")`, true},
+		{"date_only", `parseTimestamp("2026-03-24")`, false},
+		{"us_date", `parseTimestamp("03/24/2026")`, false},
+		{"rfc3339nano", `parseTimestamp("2026-03-24T19:00:00.123456789Z")`, false},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

site/src/content/docs/concepts/expressions.md

@@ -596,7 +596,7 @@ Parses an ISO 8601 / RFC 3339 string to a CEL timestamp value. Named `parseTimes
 steps:
   - name: check-expiry
     action: http/request
-    if: "parseTimestamp(steps.fetch.output.json.expires_at) < now"
+    if: "parseTimestamp(steps.fetch.output.json.expires_at) < parseTimestamp(\"2026-12-31T00:00:00Z\")"
     params:
       method: POST
       url: "https://api.example.com/renew"
@@ -619,7 +619,7 @@ steps:
         # Format as "2006-01-02" (Go layout for YYYY-MM-DD)
         report_date: "{{ formatTimestamp(parseTimestamp(steps.fetch.output.json.created_at), '2006-01-02') }}"
         # Format with time for a human-readable label
-        label: "Report for {{ formatTimestamp(now, 'Jan 2, 2006') }}"
+        label: "Report for {{ formatTimestamp(parseTimestamp(steps.fetch.output.json.created_at), 'Jan 2, 2006') }}"
 ```
 
 ## Limitations

site/src/content/docs/getting-started/data-transformations.md

@@ -260,6 +260,7 @@ These are the Mantle CEL extensions available in workflow expressions. For full
 | `.map(var, expr)` | Transform each element, returning a new list |
 | `.filter(var, expr)` | Return elements where `expr` evaluates to true |
 | `.exists(var, expr)` | True if any element satisfies `expr` |
+| `.exists_one(var, expr)` | True if exactly one element satisfies `expr` |
 | `.all(var, expr)` | True if every element satisfies `expr` |
 
 **String**