Merge pull request #49 from mgomes/mgomes/v0-18-0

v0.18.0: standard library expansion

Author: mgomes

ROADMAP.md

@@ -281,35 +281,35 @@ Goal: reduce host-side boilerplate for common scripting tasks.
 
 ### Core Utilities
 
-- [ ] Add JSON parse/stringify built-ins.
-- [ ] Add regex matching/replacement helpers.
-- [ ] Add UUID/random identifier utilities with deterministic test hooks.
-- [ ] Add richer date/time parsing helpers for common layouts.
-- [ ] Add safer numeric conversions and clamp/round helpers.
+- [x] Add JSON parse/stringify built-ins.
+- [x] Add regex matching/replacement helpers.
+- [x] Add UUID/random identifier utilities with deterministic test hooks.
+- [x] Add richer date/time parsing helpers for common layouts.
+- [x] Add safer numeric conversions and clamp/round helpers.
 
 ### Collections and Strings
 
-- [ ] Expand hash helpers for nested transforms and key remapping.
-- [ ] Expand array helpers for chunking/windowing and stable group operations.
-- [ ] Add string helpers for common normalization and templating tasks.
+- [x] Expand hash helpers for nested transforms and key remapping.
+- [x] Expand array helpers for chunking/windowing and stable group operations.
+- [x] Add string helpers for common normalization and templating tasks.
 
 ### Compatibility and Safety
 
-- [ ] Define deterministic behavior for locale-sensitive operations.
-- [ ] Add quotas/guards around potentially expensive operations.
-- [ ] Ensure new stdlib functions are capability-safe where required.
+- [x] Define deterministic behavior for locale-sensitive operations.
+- [x] Add quotas/guards around potentially expensive operations.
+- [x] Ensure new stdlib functions are capability-safe where required.
 
 ### Testing and Docs
 
-- [ ] Add comprehensive docs pages and examples for each new family.
-- [ ] Add negative tests for malformed JSON/regex patterns.
-- [ ] Add benchmark coverage for hot stdlib paths.
+- [x] Add comprehensive docs pages and examples for each new family.
+- [x] Add negative tests for malformed JSON/regex patterns.
+- [x] Add benchmark coverage for hot stdlib paths.
 
 ### v0.18.0 Definition of Done
 
-- [ ] New stdlib is documented and example-backed.
-- [ ] Runtime behavior is deterministic across supported OSes.
-- [ ] Security/performance guardrails are validated by tests.
+- [x] New stdlib is documented and example-backed.
+- [x] Runtime behavior is deterministic across supported OSes.
+- [x] Security/performance guardrails are validated by tests.
 
 ---
 

docs/arrays.md

@@ -19,6 +19,8 @@ Common enumerable helpers include:
 - `sum` to total numeric arrays.
 - `compact` to drop `nil` entries.
 - `flatten(depth = nil)` to collapse nested arrays (defaults to fully flattening).
+- `chunk(size)` to split into fixed-size slices.
+- `window(size)` to build overlapping windows.
 - `join(sep = "")` to produce a string.
 
 Example:
@@ -33,6 +35,11 @@ def total_by_multiplier(values, multiplier)
 end
 ```
 
+```vibe
+[1, 2, 3, 4, 5].chunk(2)   # [[1,2], [3,4], [5]]
+[1, 2, 3, 4].window(3)      # [[1,2,3], [2,3,4]]
+```
+
 ## Search and predicates
 
 - `include?(value)` for membership checks.
@@ -55,8 +62,12 @@ end
 - `reverse`, `sort`, and `sort_by`.
 - `partition` to split into matching and non-matching arrays.
 - `group_by` to collect values by key.
+- `group_by_stable` to collect values by key while preserving group order.
 - `tally` to count symbol/string occurrences.
 
+Sorting of strings/symbols uses deterministic codepoint ordering (locale
+collation is not applied).
+
 ```vibe
 def summarize(players)
   grouped = players.group_by { |p| p[:status] }

docs/builtins.md

@@ -56,6 +56,88 @@ end
 
 For time manipulation in VibeScript, use the `Time` object (`Time.now`, `Time.parse`, `Time.utc`, etc.). See `docs/time.md`.
 
+## Random IDs
+
+### `uuid()`
+
+Returns an RFC 4122 version 4 UUID string:
+
+```vibe
+event_id = uuid()
+```
+
+### `random_id(length = 16)`
+
+Returns an alphanumeric random identifier string:
+
+```vibe
+short = random_id(8)
+token = random_id()
+```
+
+## Numeric Conversion
+
+### `to_int(value)`
+
+Converts `int`, integral `float`, or base-10 numeric `string` values into `int`.
+
+### `to_float(value)`
+
+Converts `int`, `float`, or numeric `string` values into `float`.
+
+```vibe
+count = to_int("42")
+ratio = to_float("1.25")
+```
+
+## JSON
+
+### `JSON.parse(string)`
+
+Parses a JSON string into VibeScript values (`hash`, `array`, `string`, `int`,
+`float`, `bool`, `nil`):
+
+```vibe
+payload = JSON.parse("{\"id\":\"p-1\",\"score\":10}")
+payload[:score] # 10
+```
+
+`JSON.parse` enforces a 1 MiB input limit.
+
+### `JSON.stringify(value)`
+
+Serializes supported values (`hash`/`object`, `array`, scalar primitives) into
+a JSON string:
+
+```vibe
+raw = JSON.stringify({ id: "p-1", score: 10, tags: ["a", "b"] })
+```
+
+`JSON.stringify` enforces a 1 MiB output limit.
+
+## Regex
+
+### `Regex.match(pattern, text)`
+
+Returns the first match string or `nil` when no match exists.
+
+### `Regex.replace(text, pattern, replacement)`
+
+Replaces the first regex match in `text`.
+
+### `Regex.replace_all(text, pattern, replacement)`
+
+Replaces all regex matches in `text`.
+
+```vibe
+Regex.match("ID-[0-9]+", "ID-12 ID-34")                  # "ID-12"
+Regex.replace("ID-12 ID-34", "ID-[0-9]+", "X")           # "X ID-34"
+Regex.replace_all("ID-12 ID-34", "ID-[0-9]+", "X")       # "X X"
+Regex.replace("ID-12", "ID-([0-9]+)", "X-$1")            # "X-12"
+```
+
+Regex helpers enforce input guards (max pattern size 16 KiB, max text size 1 MiB).
+
 ## Module Loading
 
 ### `require(module_name, as: alias?)`

docs/hashes.md

@@ -45,6 +45,8 @@ end
 - `except(*keys)` removes selected keys.
 - `select` / `reject` with a block.
 - `transform_keys` / `transform_values` with a block.
+- `deep_transform_keys` for recursive key mapping across nested hashes/arrays.
+- `remap_keys(mapping_hash)` for direct key rename maps.
 
 ```vibe
 def public_profile(record)
@@ -54,6 +56,21 @@ def public_profile(record)
 end
 ```
 
+```vibe
+payload = { player_id: 7, profile: { total_raised: 12 } }
+payload.deep_transform_keys do |k|
+  if k == :player_id
+    :playerId
+  elsif k == :total_raised
+    :totalRaised
+  else
+    k
+  end
+end
+
+{ first_name: "Alex" }.remap_keys({ first_name: :name })
+```
+
 ## Iteration helpers
 
 - `keys` and `values`

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,69 @@
+# 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
+```
+
+For a runnable end-to-end sample, see `examples/stdlib/core_utilities.vibe`.

docs/strings.md

@@ -2,6 +2,12 @@
 
 VibeScript provides several methods for string manipulation.
 
+## Locale Behavior
+
+String transforms are locale-insensitive and deterministic across supported
+platforms. Methods like `upcase`, `downcase`, and `capitalize` use Unicode
+case mapping rules and do not depend on host locale settings.
+
 ## Basic Methods
 
 ### `length`
@@ -58,6 +64,15 @@ end
 clean_input("  hello  ")  # "hello"
 ```
 
+### `squish`
+
+Trims leading/trailing whitespace and collapses internal whitespace runs to a
+single space:
+
+```vibe
+"  hello \n\t world  ".squish # "hello world"
+```
+
 ### `lstrip`
 
 Removes leading whitespace:
@@ -269,6 +284,7 @@ The following methods are supported as aliases and return transformed strings.
 When there is no change, bang methods return `nil`.
 
 - `strip!`, `lstrip!`, `rstrip!`, `chomp!`
+- `squish!`
 - `delete_prefix!`, `delete_suffix!`
 - `upcase!`, `downcase!`, `capitalize!`, `swapcase!`, `reverse!`
 - `sub!`, `gsub!`
@@ -292,6 +308,23 @@ Splits a string into an array of strings.
 "path/to/file".split("/") # ["path", "to", "file"]
 ```
 
+## Templating
+
+### `template(context, strict: false)`
+
+Interpolates `{{name}}` placeholders from a hash context. Dot paths can access
+nested hashes (`{{user.name}}`).
+
+```vibe
+tpl = "Player {{user.name}} scored {{user.score}}"
+ctx = { user: { name: "Alex", score: 42 } }
+
+tpl.template(ctx) # "Player Alex scored 42"
+```
+
+When `strict: true`, missing placeholders raise an error instead of being left
+unchanged.
+
 ## Example: Text Processing
 
 ```vibe

docs/time.md

@@ -18,6 +18,7 @@ end
 - `Time.parse(string, layout=nil, in: zone)`
 
 Zones accept Go-style names (e.g. `"America/New_York"`), `"UTC"`/`"GMT"`, `"LOCAL"`, or numeric offsets like `"+05:30"`.
+Without an explicit `layout`, `Time.parse` accepts common formats such as RFC3339/RFC1123, `YYYY-MM-DD`, `YYYY/MM/DD`, `YYYY-MM-DD HH:MM:SS`, and `MM/DD/YYYY` (with optional time).
 
 ## Formatting
 

examples/arrays/extras.vibe

@@ -114,3 +114,17 @@ end
 def tally_statuses(statuses)
   statuses.tally
 end
+
+def chunk_values(values, size)
+  values.chunk(size)
+end
+
+def window_values(values, size)
+  values.window(size)
+end
+
+def group_by_stable_status(players)
+  players.group_by_stable do |player|
+    player[:status]
+  end
+end

examples/hashes/transformations.vibe

@@ -55,3 +55,21 @@ def non_zero(record)
     value == 0
   end
 end
+
+def remap_profile(record)
+  record.remap_keys({ first_name: :name, total_raised: :raised })
+end
+
+def deep_transform_profile(record)
+  record.deep_transform_keys do |key|
+    if key == :player_id
+      :playerId
+    elsif key == :total_raised
+      :totalRaised
+    elsif key == :amount_cents
+      :amountCents
+    else
+      key
+    end
+  end
+end