Document and benchmark core stdlib utilities

Author: mgomes

ROADMAP.md

@@ -303,7 +303,7 @@ Goal: reduce host-side boilerplate for common scripting tasks.
 
 - [ ] Add comprehensive docs pages and examples for each new family.
 - [x] Add negative tests for malformed JSON/regex patterns.
-- [ ] Add benchmark coverage for hot stdlib paths.
+- [x] Add benchmark coverage for hot stdlib paths.
 
 ### v0.18.0 Definition of Done
 

docs/introduction.md

@@ -30,3 +30,5 @@ dives on specific topics.
   behavior (exports, aliasing, policy hooks).
 - `examples/module_require.md` – practical example showing how to share
   helpers with `require` and module search paths.
+- `stdlib_core_utilities.md` – examples for JSON, regex, random IDs, numeric
+  conversion, and common time parsing helpers.

docs/stdlib_core_utilities.md

@@ -0,0 +1,67 @@
+# Core Stdlib Utilities
+
+This page covers the core utility helpers added in v0.18.
+
+## JSON
+
+```vibe
+def parse_payload(raw)
+  JSON.parse(raw)
+end
+
+def emit_payload(record)
+  JSON.stringify(record)
+end
+```
+
+## Regex
+
+```vibe
+def normalize_ids(text)
+  Regex.replace_all(text, "ID-[0-9]+", "X")
+end
+
+def first_id(text)
+  Regex.match("ID-[0-9]+", text)
+end
+```
+
+## Random IDs
+
+```vibe
+def new_event_id()
+  uuid()
+end
+
+def short_token()
+  random_id(8)
+end
+```
+
+## Numeric Conversion
+
+```vibe
+def parse_score(raw_score)
+  to_int(raw_score)
+end
+
+def parse_ratio(raw_ratio)
+  to_float(raw_ratio)
+end
+```
+
+## Common Time Parsing
+
+`Time.parse` accepts common formats without manually passing a layout:
+
+- RFC3339 / RFC3339Nano
+- RFC1123 / RFC1123Z
+- `YYYY-MM-DD` and `YYYY-MM-DD HH:MM:SS`
+- `YYYY/MM/DD` and `YYYY/MM/DD HH:MM:SS`
+- `MM/DD/YYYY` and `MM/DD/YYYY HH:MM:SS`
+
+```vibe
+def parse_seen_at(raw)
+  Time.parse(raw, in: "UTC")
+end
+```

vibes/execution_benchmark_test.go

@@ -157,3 +157,85 @@ end`)
 		}
 	}
 }
+
+func BenchmarkExecutionJSONParseLoop(b *testing.B) {
+	engine := benchmarkEngine()
+	script, err := engine.Compile(`def run(raw, n)
+  total = 0
+  for i in 1..n
+    payload = JSON.parse(raw)
+    total = total + payload[:score]
+  end
+  total
+end`)
+	if err != nil {
+		b.Fatalf("compile failed: %v", err)
+	}
+
+	args := []Value{
+		NewString(`{"score":7,"tags":["a","b","c"],"active":true}`),
+		NewInt(80),
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := script.Call(context.Background(), "run", args, CallOptions{}); err != nil {
+			b.Fatalf("call failed: %v", err)
+		}
+	}
+}
+
+func BenchmarkExecutionJSONStringifyLoop(b *testing.B) {
+	engine := benchmarkEngine()
+	script, err := engine.Compile(`def run(payload, n)
+  out = ""
+  for i in 1..n
+    out = JSON.stringify(payload)
+  end
+  out
+end`)
+	if err != nil {
+		b.Fatalf("compile failed: %v", err)
+	}
+
+	payload := NewHash(map[string]Value{
+		"id":     NewString("player-7"),
+		"score":  NewInt(42),
+		"active": NewBool(true),
+		"tags":   NewArray([]Value{NewString("a"), NewString("b"), NewString("c")}),
+	})
+	args := []Value{payload, NewInt(80)}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := script.Call(context.Background(), "run", args, CallOptions{}); err != nil {
+			b.Fatalf("call failed: %v", err)
+		}
+	}
+}
+
+func BenchmarkExecutionRegexReplaceAllLoop(b *testing.B) {
+	engine := benchmarkEngine()
+	script, err := engine.Compile(`def run(text, n)
+  out = ""
+  for i in 1..n
+    out = Regex.replace_all(text, "ID-[0-9]+", "X")
+  end
+  out
+end`)
+	if err != nil {
+		b.Fatalf("compile failed: %v", err)
+	}
+
+	args := []Value{
+		NewString("ID-12 ID-34 ID-56 ID-78 ID-90"),
+		NewInt(80),
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := script.Call(context.Background(), "run", args, CallOptions{}); err != nil {
+			b.Fatalf("call failed: %v", err)
+		}
+	}
+}