rip-lang 3.13.137 → 3.14.1

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-3.13.137-blue.svg" alt="Version"></a>
+  <a href="https://github.com/shreeve/rip-lang/commits/main"><img src="https://img.shields.io/badge/version-3.14.1-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%2C436%2F1%2C436-brightgreen.svg" alt="Tests"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
@@ -239,6 +239,7 @@ All use `globalThis` with `??=` — override any by redeclaring locally.
 | `*>` (merge assign) | `*>obj = {a: 1}` | `Object.assign(obj, {a: 1})` |
 | `or return` | `x = get() or return err` | Guard clause (Ruby-style) |
 | `?? throw` | `x = get() ?? throw err` | Nullish guard |
+| `:name` (symbol) | `:redo`, `:active` | Ruby-style interned symbol (`Symbol.for`) |
 
 ### Heredoc & Heregex
 
@@ -283,6 +284,47 @@ pattern = ///
 
 ---
 
+## Schema
+
+**Rip Schema** is a first-class language construct for declaring data inline. One keyword — `schema` — covers what would otherwise take three libraries: a validator (Zod-style), an ORM (Prisma/ActiveRecord-style), and a migration tool. Schemas live in `.rip` source, compile alongside the rest of your code, and are real runtime values you can export, pass around, and derive from. Unlike Rip's compile-time `type` / `interface` system (which is erased from JS output), schemas exist at runtime because they validate, construct class instances, run ORM queries, and emit SQL — all from a single declaration that your editor also type-checks via automatic shadow TypeScript.
+
+A schema has one of **five kinds**, selected by a `:symbol` after the keyword. `:input` (the default) is a field validator. `:shape` adds methods and computed getters — validators with behavior, like a `Money` or `Address` value. `:enum` declares a closed set of members using `:symbol` literals (`:draft`, `:active 1`) and exposes `.parse()` that accepts either the member name or its value. `:mixin` declares a reusable field group — non-instantiable, consumed by other schemas via `@mixin Name` with diamond-dedup and cycle detection. `:model` is the big one: DB-backed, with a full async ORM (`find`, `where`, `create`, `save`, `destroy`), migration-grade DDL emission (`toSQL`), Rails-ordered lifecycle hooks (ten recognized names from `beforeValidation` through `afterDestroy`), and `@belongs_to` / `@has_many` / `@has_one` relations that resolve lazily through a process-global registry.
+
+```coffee
+# Validator
+SignupInput = schema
+  email!    email
+  password! string, 8..100
+
+# Shape with behavior
+Address = schema :shape
+  street! string
+  city!   string
+  full: ~> "#{@street}, #{@city}"
+
+# Enumeration
+Status = schema
+  :pending 0
+  :active  1
+  :done    2
+
+# DB-backed model
+User = schema :model
+  name!   string
+  email!# email
+  @timestamps
+  @has_many Order
+  beforeValidation: -> @email = @email.toLowerCase()
+```
+
+The **body syntax is declarative**, not general Rip code. Five line forms are legal: fields (`name! type, min..max`, with inline transforms via `name! type, -> fn(it)` where `it` is the whole raw input), directives (`@timestamps`, `@mixin Name`, `@belongs_to User?`), methods (`name: -> body`), computed getters (`name: ~> body`), and eager-derived fields (`name: !> body` — computed once at parse/hydrate, stored as an own property, distinct from `~>` which re-evaluates on every access). Modifiers `!`, `#`, `?` mark required, unique, and optional; the type slot is optional and defaults to `string`. Constraints are self-identifying by shape: `min..max` for ranges, `[value]` for defaults, `/regex/` for patterns, `{key: val}` for attrs, and the terminal `-> body` for transforms. Literal-union types (`"M" | "F" | "U"`) in the type slot cover enum-style value sets. Cross-field invariants — "passwords must match", "end after start", "id OR full-object" — attach as `@ensure "message", (u) -> predicate` (or an array of such pairs), run after field validation, and collect all failures in declaration order. Every instantiable schema exposes the same three-method runtime API: `.parse(data)` returns a cleaned value or throws `SchemaError` with structured `.issues`; `.safe(data)` returns `{ok, value, errors}` without throwing; `.ok(data)` is a boolean fast path that allocates no error arrays. All three have async dammit variants — `User.find! 1`, `user.save!` — that are the idiomatic form in Rip source.
+
+**`:model` is where the pieces converge.** One declaration gives you a validator, a class with fields as enumerable own properties and methods/getters on the prototype, a chainable async query builder (`User.where(active: true).order("last_name").all!`), migration DDL that works standalone (`User.toSQL()` never touches the database), belongs-to/has-many accessors that resolve cross-module through the registry, and full shadow TypeScript with `ModelSchema<Instance, Data>` typing that propagates through schema algebra. Hydrated instances carry both snake_case and camelCase aliases on DB-derived columns (`order.user_id` and `order.userId` read the same slot), so raw SQL helpers and ORM access coexist cleanly. A single-function adapter interface (`adapter.query(sql, params)`) routes all database I/O, so tests use in-memory mocks and production uses rip-db without the ORM caring.
+
+**Schema algebra** — `.pick`, `.omit`, `.partial`, `.required`, `.extend` — always returns a new `:shape`. Field semantics (type, literal unions, constraints, inline transforms) carry through to the derived shape; instance behavior (methods, computed `~>`, eager-derived `!>`, hooks, and `@ensure` refinements) does not. `User.omit "password"` produces a validator for `User` minus the password field; it won't have `.find()` or the `beforeSave` hook, but field-level transforms (`email, -> it.email.toLowerCase()`) continue to fire on the derived shape exactly as they did on the original. This invariant is enforced both at runtime (ORM methods throw on derived shapes with a targeted diagnostic pointing at query projection) and at the TypeScript level (algebra generics are parameterized over `Data`, not `Instance`, so the derived types correctly omit methods and ORM surface). Internally, the whole feature is a compiler sidecar — 54% of the implementation lives in `src/schema.js` and touches the core compiler in under 100 lines of wiring. A four-layer lazy runtime (raw descriptor → normalized metadata → validator plan → ORM plan / DDL plan) means module load is cheap, migration scripts never build the ORM plan, and validator-only consumers never build the class machinery. The full reference is in [docs/RIP-SCHEMA.md](docs/RIP-SCHEMA.md).
+
+---
+
 ## vs React / Vue / Solid
 
 | Concept | React | Vue | Solid | Rip |
@@ -434,7 +476,7 @@ Rip includes optional packages for full-stack development:
 | [@rip-lang/ui](packages/ui/) | — | Unified UI system — browser widgets, email components, shared helpers, Tailwind integration |
 | [@rip-lang/swarm](packages/swarm/) | 1.2.18 | Parallel job runner with worker pool |
 | [@rip-lang/csv](packages/csv/) | 1.3.6 | CSV parser + writer |
-| [@rip-lang/schema](packages/schema/) | 0.3.8 | Unified schema → TypeScript types, SQL DDL, validation, ORM |
+| [@rip-lang/time](packages/time/) | 1.0.0 | Immutable date/time with IANA timezones + `Duration` (US-English, zero runtime deps) |
 | [VS Code Extension](packages/vscode/) | 0.5.7 | Syntax highlighting, type intelligence, source maps |
 
 ```bash
@@ -504,8 +546,8 @@ bun run bump major
 |-------|-------------|
 | [docs/RIP-LANG.md](docs/RIP-LANG.md) | Full language reference (syntax, operators, reactivity, types, components) |
 | [docs/RIP-TYPES.md](docs/RIP-TYPES.md) | Type system specification |
-| [AGENTS.md](AGENTS.md) | Compiler architecture, S-expressions, component system internals |
-| [AGENTS.md](AGENTS.md) | AI agents — get up to speed for working on the compiler |
+| [docs/RIP-SCHEMA.md](docs/RIP-SCHEMA.md) | Schema keyword — validators, models, ORM, DDL, algebra |
+| [AGENTS.md](AGENTS.md) | AI agents — compiler architecture, subsystems, conventions |
 
 ---
 

package/docs/RIP-LANG.md

@@ -116,6 +116,12 @@ table = *{
   null: "nothing"
 }
 
+# Symbols — Ruby-style interned symbols via Symbol.for()
+status = :active              # Symbol.for("active")
+state = :ready                # Symbol.for("ready")
+:redo is :redo                # true (globally interned)
+typeof :hello                 # "symbol"
+
 # Ranges
 nums = [1..5]      # [1, 2, 3, 4, 5]
 exclusive = [1...5]  # [1, 2, 3, 4]
@@ -337,6 +343,7 @@ Multiple lines
 | `not of` | Not of | `k not of obj` | Negated key existence |
 | `<=>` | Two-way bind | `value <=> name` | Bidirectional reactive binding (render blocks) |
 | `*{ }` | Map literal | `*{/pat/: val}` | `new Map([[/pat/, val]])` |
+| `:name` | Symbol literal | `:redo` | `Symbol.for("redo")` — Ruby-style interned symbol |
 
 ## Assignment Operators
 
@@ -1295,7 +1302,6 @@ Rip includes optional packages for full-stack development. All are written in Ri
 ```bash
 bun add @rip-lang/server         # Web framework + production server
 bun add @rip-lang/db             # DuckDB server + client
-bun add @rip-lang/schema         # ORM + validation
 bun add @rip-lang/swarm          # Parallel job runner
 bun add @rip-lang/csv            # CSV parser + writer
 # Widgets are included in packages/ui/ (not a separate npm package)
@@ -1691,22 +1697,65 @@ rows = CSV.read "name,age\nAlice,30\nBob,25\n", headers: true
 CSV.save! 'output.csv', rows
 ```
 
-## @rip-lang/schema — ORM + Validation
+## schema — Inline validators, models, and DDL
+
+The `schema` keyword declares a runtime data description inline — a
+validator, a domain shape, an enumeration, a reusable field group, or a
+full DB-backed model. One keyword covers input validation, class
+generation, persistence, migration DDL, and shadow TypeScript.
 
 ```coffee
-import { Model } from '@rip-lang/schema'
+# Validator
+SignupInput = schema
+  email!     email
+  password!  8..100
+  password2! 8..100
+
+  @ensure "passwords must match", (u) -> u.password is u.password2
+
+# Shape with behavior
+Address = schema :shape
+  street! string
+  city!   string
+  full: ~> "#{@street}, #{@city}"
+
+# Enumeration
+Status = schema
+  :pending 0
+  :active  1
+  :done    2
+
+# DB-backed model with ORM and migrations
+User = schema :model
+  name!   string
+  email!# email
+  @timestamps
+  @has_many Order
+  beforeValidation: -> @email = @email.toLowerCase()
 
-class User extends Model
-  @table = 'users'
-  @schema
-    name:  { type: 'string', required: true }
-    email: { type: 'email', unique: true }
+# Usage
+input  = SignupInput.parse rawJson     # throws SchemaError on invalid
+result = SignupInput.safe  rawJson     # {ok, value, errors}
+valid  = SignupInput.ok    rawJson     # boolean
 
-user = User.find!(25)
-user.name = 'Alice'
-user.save!()
+user   = User.create! name: "Alice", email: "a@b.c"
+orders = user.orders!                  # Promise<OrderInstance[]>
+sql    = User.toSQL()
+
+UserPublic = User.omit "password"      # algebra returns :shape
 ```
 
+Body forms: fields (`name! type`, with optional range/regex/default/attrs
+and terminal `-> transform`), methods (`name: -> body`), computed getters
+(`name: ~> body`), eager-derived fields (`name: !> body`), directives
+(`@mixin`, `@timestamps`, `@has_many`, `@belongs_to`, `@index`,
+`@softDelete`), and `@ensure "msg", (x) -> predicate` cross-field
+refinements. Inline and array forms are both accepted for `@ensure`.
+
+**See [docs/RIP-SCHEMA.md](./RIP-SCHEMA.md) for the comprehensive guide** —
+all five kinds, every body form, the ORM and DDL contract, hooks, mixins,
+algebra, shadow TypeScript, and the architecture.
+
 ## Full-Stack Example
 
 A complete API server in Rip:
@@ -1985,6 +2034,58 @@ class EventEmitter
     @
 ```
 
+## Conversion Method Naming
+
+When a type exposes methods that convert between representations, Rip
+follows a convention borrowed from Rust, Swift, and .NET for naming
+them. The prefix signals what kind of thing you get back:
+
+| Prefix    | Meaning                                   | What you get                                    |
+| --------- | ----------------------------------------- | ----------------------------------------------- |
+| `toX()`   | Convert — produce a new independent value | New object; mutating it doesn't affect `self`   |
+| `asX()`   | View / cast — reinterpret `self` as an `X` | Wrapper or lens; may share state with `self`    |
+| `fromX()` | Static constructor from an `X`            | New instance built from external data           |
+| `parseX`  | Parse an `X`-formatted representation     | Validated, typed value                          |
+
+The test when naming your own method: **if mutating the returned value
+can affect the original, it's `as`; otherwise it's `to`.** Equivalently:
+did real work happen (allocation, copy, serialization)? Then `to`.
+Zero-cost reinterpretation? Then `as`.
+
+```coffee
+# toX — converts, produces an independent value
+user.toJSON()         # plain object; mutating it doesn't change user
+user.toPublic()       # filtered plain object for wire responses
+User.toSQL()          # CREATE TABLE DDL string
+events.toArray()      # materialized Array from an iterator / Set
+
+# asX — reinterprets, may share state
+# No Rip idioms today; reserved for zero-cost views. A future
+# buffer.asUint8Array() would wrap the same memory, not copy it.
+
+# fromX — static construction from another type
+Array.from(iter)
+String.fromCharCode(65)
+
+# parseX — typed parse from a wire / string format
+Schema.parse(data)    # validates, returns a typed instance
+parseInt("42")
+```
+
+`parse` and `to` are duals: `Schema.parse(data)` takes a wire
+representation in, `instance.toJSON()` produces one out. Picking the
+right prefix ahead of time keeps the pair discoverable without
+remembering which method name you chose last time.
+
+Related prefixes worth recognizing from other ecosystems, even though
+Rip doesn't have idiomatic uses today:
+
+- `intoX` — consume `self`, return `X` (Rust's ownership transfer).
+  JS garbage collection makes ownership invisible, so Rip just uses
+  `toX` for the same cases.
+- `withX` — immutable update returning a modified copy of `self` with
+  one field changed. Useful for record types with many optional fields.
+
 ---
 
 # 16. Quick Reference
@@ -2042,6 +2143,10 @@ a ?? b         # nullish coalescing
 # Word arrays
 %w[foo bar baz]   # ["foo", "bar", "baz"] — Ruby-style word literal
 
+# Symbol literals — Ruby-style interned symbols
+:redo             # Symbol.for("redo")
+:active           # Symbol.for("active")
+
 # Map literals — real Map with any key type
 *{ /regex/: val, "key": val, 42: val }