rip-lang 3.13.3 → 3.13.4

package/README.md

@@ -11,7 +11,7 @@
 <p align="center">
   <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-3.13.3-blue.svg" alt="Version"></a>
   <a href="#zero-dependencies"><img src="https://img.shields.io/badge/dependencies-ZERO-brightgreen.svg" alt="Dependencies"></a>
-  <a href="#"><img src="https://img.shields.io/badge/tests-1%2C243%2F1%2C243-brightgreen.svg" alt="Tests"></a>
+  <a href="#"><img src="https://img.shields.io/badge/tests-1%2C251%2F1%2C251-brightgreen.svg" alt="Tests"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
 </p>
 
@@ -172,6 +172,29 @@ enum HttpCode                            # Runtime enum
 
 Compiles to `.js` (types erased) + `.d.ts` (types preserved) — full IDE support via TypeScript Language Server. See [docs/RIP-TYPES.md](docs/RIP-TYPES.md).
 
+### Standard Library
+
+13 global helpers available in every Rip program — no imports needed:
+
+```coffee
+p "hello"                       # console.log shorthand
+pp {name: "Alice", age: 30}     # pretty-print JSON (also returns value)
+warn "deprecated"               # console.warn
+assert x > 0, "must be positive"
+raise TypeError, "expected string"
+todo "finish this later"
+kind [1, 2, 3]                  # "array" (fixes typeof)
+rand 10                         # 0-9
+rand 5, 10                      # 5-10 inclusive
+sleep! 1000                     # await sleep(1000)
+exit 1                          # process.exit(1)
+abort "fatal"                   # log to stderr + exit(1)
+zip names, ages                 # [[n1,a1], [n2,a2], ...]
+noop                            # () => {}
+```
+
+All use `globalThis` with `??=` — override any by redeclaring locally.
+
 ---
 
 ## Operators
@@ -180,7 +203,8 @@ Compiles to `.js` (types erased) + `.d.ts` (types preserved) — full IDE suppor
 |----------|---------|--------------|
 | `!` (dammit) | `fetchData!` | Calls AND awaits |
 | `!` (void) | `def process!` | Suppresses implicit return |
-| `!?` (otherwise) | `val !? 5` | Default only if `undefined` |
+| `!?` (otherwise) | `val !? 5` | Default only if `undefined` (infix) |
+| `!?` (defined) | `val!?` | True if not `undefined` (postfix) |
 | `?` (existence) | `x?` | True if `x != null` |
 | `?:` (ternary) | `x > 0 ? 'yes' : 'no'` | JS-style ternary expression |
 | `if...else` (postfix) | `"yes" if cond else "no"` | Python-style ternary expression |
@@ -403,7 +427,7 @@ rip file.rip           # Run
 rip -c file.rip        # Compile
 rip -t file.rip        # Tokens
 rip -s file.rip        # S-expressions
-bun run test           # 1243 tests
+bun run test           # 1251 tests
 bun run parser         # Rebuild parser
 bun run browser        # Build browser bundle
 ```
@@ -417,7 +441,7 @@ bun run browser        # Build browser bundle
 | [docs/RIP-LANG.md](docs/RIP-LANG.md) | Full language reference (syntax, operators, reactivity, types, future ideas) |
 | [docs/RIP-INTERNALS.md](docs/RIP-INTERNALS.md) | Compiler architecture (lexer, parser, codegen, S-expressions) |
 | [docs/RIP-TYPES.md](docs/RIP-TYPES.md) | Type system specification |
-| [AGENT.md](AGENT.md) | AI agents — get up to speed for working on the compiler |
+| [AGENTS.md](AGENTS.md) | AI agents — get up to speed for working on the compiler |
 
 ---
 

package/bin/rip

@@ -12,6 +12,12 @@ import packageJson from '../package.json' with { type: 'json' };
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// Set NODE_PATH so spawned processes and workers can resolve @rip-lang/* packages
+const _nodeModules = join(__dirname, '..', '..');
+if (!process.env.NODE_PATH?.split(':').includes(_nodeModules)) {
+  process.env.NODE_PATH = [_nodeModules, process.env.NODE_PATH].filter(Boolean).join(':');
+}
+
 const VERSION = packageJson.version;
 const SUMMARY = packageJson.description;
 

package/docs/RIP-INTERNALS.md

@@ -562,6 +562,19 @@ rip> .sexp    # Toggle s-expression display
 rip> .js      # Toggle JS display
 ```
 
+## REPL Architecture
+
+The CLI REPL (`src/repl.js`) uses a `vm`-based sandbox with two eval paths:
+
+- **Primary:** `vm.runInContext` with async IIFE wrapper — handles all code including `await`
+- **Fallback:** `vm.SourceTextModule` — used only when `import` statements are present (required for module linking)
+
+This split works around Bun bug [#22287](https://github.com/oven-sh/bun/issues/22287) where `vm.SourceTextModule` crashes on top-level `await`.
+
+The stdlib is injected once at REPL startup via `getStdlibCode()` — the same function the compiler uses, ensuring a single source of truth. Variables persist across evaluations via a `__vars` object.
+
+The browser REPL (`docs/index.html`) uses a hidden iframe as its sandbox. Code is compiled with `skipPreamble: true` and wrapped in an async IIFE for `await` support. The stdlib and reactive runtime are injected into the iframe context at initialization.
+
 ---
 
 # 9. Future Work

package/docs/RIP-LANG.md

@@ -21,9 +21,10 @@ Rip is a modern reactive language that compiles to ES2022 JavaScript. It combine
 11. [CLI Tools & Scripts](#11-cli-tools--scripts)
 12. [Types](#12-types)
 13. [JavaScript Interop](#13-javascript-interop)
-14. [Common Patterns](#14-common-patterns)
-15. [Quick Reference](#15-quick-reference)
-16. [Future Ideas](#16-future-ideas)
+14. [Standard Library](#14-standard-library)
+15. [Common Patterns](#15-common-patterns)
+16. [Quick Reference](#16-quick-reference)
+17. [Future Ideas](#17-future-ideas)
 
 ---
 
@@ -293,6 +294,7 @@ Multiple lines
 | `in` | `x in arr` | Array membership |
 | `of` | `k of obj` | Object key existence |
 | `?` (postfix) | `a?` | Existence check (`a != null`) |
+| `!?` (postfix) | `a!?` | Defined check (`a !== undefined`) |
 | `?` (ternary) | `a ? b : c` | Ternary conditional |
 | `if...else` (postfix) | `b if a else c` | Python-style ternary |
 | `?.` `?.[]` `?.()` | `a?.b` `a?.[0]` `a?.()` | Optional chaining (ES6) |
@@ -311,7 +313,8 @@ Multiple lines
 | `%%` | True modulo | `-1 %% 3` | Always positive result (not remainder) |
 | `!` | Dammit | `fetchData!` | `await fetchData()` — calls AND awaits |
 | `!` | Void | `def process!` | Suppresses implicit return |
-| `!?` | Otherwise | `val !? 5` | Default if undefined or throws |
+| `!?` | Otherwise | `val !? 5` | Default if undefined (infix) |
+| `!?` | Defined | `val!?` | True if not undefined (postfix) |
 | `=~` | Match | `str =~ /pat/` | Ruby-style regex match, captures in `_` |
 | `::` | Prototype | `String::trim` | `String.prototype.trim` |
 | `[-n]` | Negative index | `arr[-1]` | `arr.at(-1)` |
@@ -374,15 +377,34 @@ level = score > 90 ? 'A' : score > 80 ? 'B' : score > 70 ? 'C' : 'F'
 item = found ? (arr[0]) : default
 ```
 
-## Otherwise Operator (`!?`)
+## Otherwise Operator (`!?`) and Defined Check (`!?`)
 
-Handles both null/undefined AND thrown errors:
+The `!?` token serves two roles, distinguished by spacing:
+
+**Infix (spaced) — otherwise:** Provides a fallback when a value is `undefined`:
+
+```coffee
+result = getValue() !? "default"
+# If getValue() returns undefined, result = "default"
+# null, 0, false, "" all pass through unchanged
+```
+
+**Postfix (unspaced) — defined check:** Returns `true` if a value is not `undefined`:
 
 ```coffee
-result = riskyOperation() !? "default"
-# If riskyOperation() throws or returns null/undefined, result = "default"
+value!?              # (value !== undefined)
+
+# Useful in comprehensions for filtering defined keys
+keys = (k for k, v of obj when v!?)
 ```
 
+The postfix form mirrors `?` (existence check) but with tighter semantics:
+
+| Operator | Checks | `null` | `undefined` | `0` | `false` | `""` |
+|----------|--------|--------|-------------|-----|---------|------|
+| `v?` | not nullish | false | false | true | true | true |
+| `v!?` | not undefined | true | false | true | true | true |
+
 ## Method Assignment (`.=`)
 
 A Rip original. Compound assignment for method calls — apply a method to a
@@ -1520,7 +1542,73 @@ const { code } = compile('x = 42');
 
 ---
 
-# 14. Common Patterns
+# 14. Standard Library
+
+Rip includes 13 global helper functions, always available in every compiled
+program. They're injected via `globalThis` using `??=`, so they won't override
+existing definitions and can be shadowed by redeclaring locally.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `abort(msg?)` | Log to stderr, exit with code 1 | `abort "fatal error"` |
+| `assert(v, msg?)` | Throw if falsy | `assert x > 0, "positive"` |
+| `exit(code?)` | Exit process | `exit 1` |
+| `kind(v)` | Lowercase type name (fixes `typeof`) | `kind [] # "array"` |
+| `noop()` | No-op function | `onClick ?= noop` |
+| `p(...args)` | `console.log` shorthand | `p "hello"` |
+| `pp(v)` | Pretty-print JSON, returns value | `pp user` |
+| `raise(a, b?)` | Throw error | `raise TypeError, "bad"` |
+| `rand(a?, b?)` | Random number | `rand 5, 10 # 5-10` |
+| `sleep(ms)` | Promise-based delay | `sleep! 1000` |
+| `todo(msg?)` | Throw "Not implemented" | `todo "finish later"` |
+| `warn(...args)` | `console.warn` shorthand | `warn "deprecated"` |
+| `zip(...arrays)` | Zip arrays pairwise | `zip names, ages` |
+
+## Usage
+
+```coffee
+# Output
+p "hello"                         # prints to stdout
+pp {name: "Alice", age: 30}       # pretty-print, returns value
+warn "this API is deprecated"     # prints to stderr
+
+# Errors
+assert users.length > 0, "no users found"
+raise TypeError, "expected a string"
+todo "implement caching"
+
+# Utilities
+kind [1, 2, 3]                    # "array" (not "object" like typeof)
+kind null                         # "null" (not "object" like typeof)
+rand 10                           # integer 0-9
+rand 5, 10                        # integer 5-10 inclusive
+rand                              # float 0.0-1.0
+
+# Async (using the ! dammit operator)
+sleep! 1000                       # pause for 1 second
+data = fetch! url                 # await fetch
+
+# Control
+exit                              # exit with code 0
+abort "something went wrong"      # log error + exit(1)
+onClick ?= noop                   # default no-op handler
+
+# Combine arrays
+zip ["alice", "bob"], [30, 25]    # [["alice", 30], ["bob", 25]]
+```
+
+## Design
+
+- **Always available** — injected into every compiled file, the CLI REPL, and the browser REPL
+- **Overridable** — `globalThis.p ??=` means your own `p = myLogger` shadows it cleanly
+- **Idempotent** — safe in multi-file apps; `??=` only sets if not already defined
+- **Inspired by** Ruby (`p`, `pp`, `raise`, `rand`), Rust (`assert`, `todo`), Python (`zip`), Kotlin (`todo`)
+
+---
+
+# 15. Common Patterns
 
 ## Error Handling
 
@@ -1536,6 +1624,9 @@ finally
 # Otherwise operator for defaults
 value = riskyOperation() !? "default"
 
+# Defined check for filtering
+keys = (k for k, v of data when v!?)
+
 # Optional chaining for safety
 name = user?.profile?.name ?? "Anonymous"
 ```
@@ -1602,7 +1693,7 @@ class EventEmitter
 
 ---
 
-# 15. Quick Reference
+# 16. Quick Reference
 
 ## Syntax Cheat Sheet
 
@@ -1643,7 +1734,8 @@ X.new(a: 1)
 
 # Operators
 a!             # await a()
-a !? b         # a if defined, else b
+a !? b         # a if defined, else b (infix otherwise)
+a!?            # true if a is defined (postfix defined check)
 a // b         # floor divide
 a %% b         # true modulo
 a =~ /pat/     # regex match, captures in _
@@ -1698,67 +1790,11 @@ count = 10  # Logs: "Count: 10, Doubled: 20"
 
 ---
 
-# 16. Future Ideas
+# 17. Future Ideas
 
 Ideas and candidates that have been discussed but not yet implemented.
 
-## Standard Library (`stdlib`)
-
-Rip is a zero-dependency language, but a small standard library of useful
-utilities would save users from writing the same one-liners in every project.
-These are **not** language features — they're plain functions that could ship
-as a prelude or optional import.
-
-### Candidates
-
-```coffee
-# Printing (Ruby's p)
-p = console.log
-
-# Exit with optional code (uses implicit `it`)
-exit = -> process.exit(it)
-
-# Tap — call a function for side effects, return the original value
-# Useful in pipe chains: data |> tap(console.log) |> process
-tap = (v, fn) -> fn(v); v
-
-# Identity — returns its argument unchanged
-# Useful as a default callback: items.filter(id)
-id = -> it
-
-# No-op — does nothing
-# Useful as a default handler: onClick ?= noop
-noop = ->
-
-# String method aliases (shorter names for common checks)
-String::starts = String::startsWith
-String::ends   = String::endsWith
-String::has    = String::includes
-
-# Clamp a value to a range
-clamp = (v, lo, hi) -> Math.min(Math.max(v, lo), hi)
-
-# Sleep for N milliseconds (returns a Promise)
-sleep = (ms) -> new Promise (resolve) -> setTimeout resolve, ms
-
-# Times helper — call a function N times, collect results
-times = (n, fn) -> (fn(i) for i in [0...n])
-```
-
-### Design Questions
-
-- **Prelude vs import?** Should these be injected automatically (like Go's
-  `fmt` or Rip's reactive runtime), or explicitly imported (`import { p, tap }
-  from '@rip-lang/std'`)? Leaning toward explicit — Rip's philosophy is zero
-  magic in the output.
-
-- **Scope?** Keep it tiny. A stdlib that grows to 500 functions defeats the
-  purpose. Each entry should save real keystrokes on something people do
-  constantly.
-
-- **Node vs Browser?** Some helpers (like `exit`) are Node-only. Others (like
-  `p`, `tap`, `sleep`) work everywhere. May want to split into `std` (universal)
-  and `std/node` (server-only).
+> **Note:** The standard library was implemented in v3.13.0. See [Section 14](#14-standard-library).
 
 ## Future Syntax Ideas
 
@@ -1792,8 +1828,8 @@ Each would need design discussion before building.
 | **[RIP-LANG.md](RIP-LANG.md)** | Full language reference (this file) |
 | **[RIP-TYPES.md](RIP-TYPES.md)** | Type system specification |
 | **[RIP-INTERNALS.md](RIP-INTERNALS.md)** | Compiler architecture & design decisions |
-| **[AGENT.md](../AGENT.md)** | AI agent guide for working on the compiler |
+| **[AGENTS.md](../AGENTS.md)** | AI agent guide for working on the compiler |
 
 ---
 
-*Rip 3.10 — 1,243 tests — Zero dependencies — Self-hosting — ~13,500 LOC*
+*Rip 3.13 — 1,244 tests — Zero dependencies — Self-hosting — ~13,500 LOC*