rip-lang 3.15.4 → 3.16.1

package/docs/RIP-SCHEMA.md

@@ -891,14 +891,19 @@ User
 Every `:model` instance carries:
 
 ```coffee
-user.save!         # validate, run hooks, INSERT or UPDATE
-user.destroy!      # run hooks, DELETE (or UPDATE deleted_at for @softDelete)
-user.ok()          # boolean — current fields validate
-user.errors()      # SchemaIssue[] — current fields' errors
-user.toJSON()      # plain object of own enumerable properties
-                   #   (id, declared fields, @timestamps columns, @softDelete
-                   #    deletedAt, @belongs_to FKs, !> eager-derived — but NOT
-                   #    methods, ~> computed getters, or internal state)
+user.save!              # validate, run hooks, INSERT or UPDATE
+user.destroy!           # run hooks, DELETE (or UPDATE deleted_at for @softDelete)
+user.ok()               # boolean — current fields validate
+user.errors()           # SchemaIssue[] — current fields' errors
+user.toJSON()           # plain object of own enumerable properties
+                        #   (id, declared fields, @timestamps columns, @softDelete
+                        #    deletedAt, @belongs_to FKs, !> eager-derived — but NOT
+                        #    methods, ~> computed getters, or internal state)
+user.savedChanges       # Map<fieldName, [oldValue, newValue]> from the most
+                        #   recent save() — empty Map when nothing was written
+user.markDirty 'name'   # force a column into the next UPDATE; escape hatch
+                        #   for in-place mutations of object-valued fields
+                        #   that === can't see (json, Date, etc.)
 ```
 
 Plus any methods, computed getters, and relation accessors you declared
@@ -907,6 +912,114 @@ on the schema. Naming tip: methods that produce a fresh projection
 `to` / `as` / `from` / `parse` conversion convention — see
 [RIP-LANG.md §15 "Conversion Method Naming"](./RIP-LANG.md#conversion-method-naming).
 
+### What `save()` actually writes
+
+The runtime tracks a snapshot of declared-field and `@belongs_to` FK
+column values at hydrate / INSERT / UPDATE time. On `.save()` it
+compares current values against the snapshot and emits a column-
+targeted UPDATE that touches **only the columns whose values changed**.
+If nothing changed, no SQL is issued at all.
+
+Two practical consequences:
+
+1. **No-op saves are free.** Calling `.save()` on an unchanged row is
+   a no-op — no DB round-trip, no row touched. Mirrors Active Record
+   with `partial_writes`.
+2. **`@timestamps` `updated_at` is bumped only on real writes.**
+   Calling `.save()` with no actual changes does NOT bump
+   `updated_at` (which would defeat the no-op-save optimization
+   entirely). Bumped on every UPDATE that does write something.
+
+A third practical consequence on DuckDB specifically: column-targeted
+UPDATEs sidestep DuckDB's foreign-key restriction on indexed-column
+updates of referenced parent rows. See
+[`docs/RIP-DUCKDB.md`](./RIP-DUCKDB.md) for the full rule, what works,
+what doesn't, and how to design around it.
+
+The diff is observable as `inst.savedChanges` after the save returns
+(or inside `afterCreate` / `afterUpdate` / `afterSave` hooks). Same
+shape as Active Record's `saved_changes`:
+
+```coffee
+order = Order.find! 1                # snapshot captured
+order.notes  = "expedited"
+order.userId = 9                     # @belongs_to User FK
+order.save!
+
+order.savedChanges                   # Map(2) {"notes" => [null, "expedited"], "userId" => [7, 9]}
+order.savedChanges.size              # 2
+order.savedChanges.has 'notes'       # true
+```
+
+INSERT records `[null, newValue]` for every field/FK that was written;
+UPDATE records `[oldValue, newValue]` for every field/FK whose value
+actually changed. `@timestamps` columns appear with the new ISO
+timestamp on real INSERTs and UPDATEs.
+
+Hook firing matches Active Record exactly: `before*` and `after*` hooks
+fire on every successful `.save()`, regardless of whether SQL was
+emitted. Hooks differentiate real writes from no-ops by checking
+`@savedChanges.size` or specific keys.
+
+### In-place mutation of object-valued fields
+
+The dirty check uses value identity (`===` with NaN handling). Setter
+assignments are detected:
+
+```coffee
+user.settings = {theme: "light", notifications: true}    # new reference; detected
+user.save!
+```
+
+In-place mutations are **not**:
+
+```coffee
+user.settings.theme = "light"                            # same reference; invisible
+user.save!                                               # nothing written
+```
+
+This matches Active Record's behavior with serialized attributes —
+"Active Record by default does not detect changes inside mutable
+serialized attributes." The escape hatch is `markDirty`:
+
+```coffee
+user.settings.theme = "light"
+user.markDirty 'settings'                                # AR's `settings_will_change!`
+user.save!                                               # writes settings = '{"theme":"light",...}'
+```
+
+`markDirty` accepts both camelCase and snake_case names, validates
+against declared fields and `@belongs_to` FK column names, and throws
+on unknown names or non-persisted instances (INSERT writes every set
+field, so `markDirty` there would be a silent no-op).
+
+Same caveat applies to `Date` fields:
+
+```coffee
+order.collectedAt.setHours 5                             # in-place; invisible
+order.markDirty 'collectedAt'
+order.save!
+```
+
+If you find yourself reaching for `markDirty` often, prefer immutable
+updates instead — they're cleaner and the dirty check sees them
+automatically:
+
+```coffee
+user.settings = { ...user.settings, theme: "light" }
+order.collectedAt = new Date order.collectedAt.getTime() + 3600000
+```
+
+### Re-entry guard
+
+`.save()` cannot be re-entered on the same instance while a save is
+already in flight. Calling `@save!` from inside this instance's
+`beforeSave` / `beforeUpdate` / `afterSave` hook throws — that's
+almost always a recursion bug, and silent infinite-loop debugging is
+worse than a clear error. The guard is per-instance: independent
+instances saving in parallel are unaffected, and sequential saves on
+the same instance work fine.
+
 ### Lifecycle hooks
 
 Hooks are methods whose name matches one of the [ten recognized hook
@@ -1083,6 +1196,76 @@ Order.create! userId:  7, total: 100    # same result
 
 Use whichever reads better alongside nearby raw SQL or JSON payloads.
 
+### Field-name conventions
+
+The snake_case ↔ camelCase bijection only works for identifiers
+that round-trip cleanly. The schema runtime enforces canonical
+camelCase at definition time:
+
+```coffee
+User = schema :model
+  mdmId? string                        # OK — canonical
+  mdmID? string                        # error — acronym style;
+                                       #   round-trips to mdm_i_d / mdmID
+                                       #   ambiguously
+```
+
+Rules:
+
+- Lowercase-first
+- Alphanumeric body
+- No two consecutive uppercase letters anywhere
+
+Same convention as Java Beans, Swift's "Acronyms in API names"
+guidance, and what most JS/TS codebases follow in practice.
+
+The runtime also reserves the names of its instance API
+(`save`, `destroy`, `ok`, `errors`, `toJSON`, `savedChanges`,
+`markDirty`, `_dirty` / `_persisted` / `_snapshot` / `_saving`)
+and the implicit timestamp / soft-delete columns
+(`createdAt`, `updatedAt`, `deletedAt`). Declaring any of those
+as a user field on a `:model` raises a `'reserved ORM name'`
+collision error at definition time. (Mixins are exempt — they
+can declare `createdAt` / `updatedAt` for explicit control,
+which is the alternative to the `@timestamps` directive.)
+
+### Relation target names
+
+`@belongs_to TargetName` derives the FK column from the target's
+PascalCase name via `__schemaSnake(target) + '_id'`. The same
+camelCase / snake_case bijection rule applies in reverse: target
+names should be canonical PascalCase (`User`, `UserOrg`, not
+`MDMUser`) so the derived FK column round-trips cleanly. Acronym-
+style target names aren't currently rejected at definition time,
+but writing `@belongs_to MDMUser` produces FK column `m_d_m_user_id`
+— almost certainly not what you want. Stick to PascalCase.
+
+### SQL reserved words
+
+The runtime always quotes column names in generated SQL — every
+INSERT, UPDATE, and SELECT it emits surrounds column identifiers
+with `"..."`. So a field named `order` works fine through the
+ORM:
+
+```coffee
+Trade = schema :model
+  order! integer                       # works through the ORM
+```
+
+The compiled SQL is `UPDATE "trades" SET "order" = ? WHERE "id" = ?`.
+
+The catch is **raw SQL** that you write yourself via the adapter's
+`query()` method or via `query!`. There the reserved-word collision
+becomes your problem:
+
+```coffee
+result = query! "SELECT order FROM trades"          # syntax error
+result = query! "SELECT \"order\" FROM trades"      # works
+```
+
+This matches Active Record's behavior — the ORM-generated SQL is
+always quoted, and raw SQL is always the user's responsibility.
+
 ---
 
 ## 9. Mixins

package/docs/RIP-TYPES.md

@@ -59,10 +59,7 @@ Both compile to identical JavaScript.
 |-------|---------|---------|
 | `::` | Type annotation | `count:: number = 0` |
 | `type` | Type alias | `type ID = number` |
-| `?` | Optional value (`T \| undefined`) | `email:: string?` |
-| `??` | Nullable value (`T \| null \| undefined`) | `middle:: string??` |
-| `!` | Non-nullable (`NonNullable<T>`) | `id:: ID!` |
-| `?:` | Optional property | `email?: string` |
+| `?::` | Optional parameter / field / prop | `email?:: string` |
 | `\|` | Union member | `"a" \| "b" \| "c"` |
 | `=>` | Function type arrow | `(a: number) => string` |
 | `<T>` | Generic parameter | `Container<T>` |
@@ -284,106 +281,78 @@ type Dictionary = {
 
 ## Optionality Modifiers
 
-Lightweight suffix operators that map directly to TypeScript unions.
+Rip uses a single optionality marker: `?` placed on the **name**
+(parameter, type-alias field, structural field, or component prop)
+**before** the `::` annotation sigil. There are no `T?` / `T??` / `T!`
+type-suffix operators — write `T | undefined`, `T | null | undefined`,
+or `NonNullable<T>` directly when you need them.
 
-### Optional: `T?`
-
-Indicates a value may be undefined.
+### Optional Parameter / Field: `name?:: T`
 
 ```coffee
-email:: string?
-callback:: Function?
-```
-
-**Emits:**
-
-```ts
-email: string | undefined
-callback: Function | undefined
-```
+def greet(name?:: string):: void
+  console.log "hello #{name ?? 'world'}"
 
-### Nullable Optional: `T??`
-
-Indicates a value may be null or undefined.
-
-```coffee
-middle:: string??
-cache:: Map<string, any>??
+type User =
+  id:: number
+  name:: string
+  email?:: string      # Optional field — may be absent
 ```
 
 **Emits:**
 
 ```ts
-middle: string | null | undefined
-cache: Map<string, any> | null | undefined
-```
-
-### Non-Nullable: `T!`
+function greet(name?: string): void { ... }
 
-Asserts a value is never null or undefined.
-
-```coffee
-id:: ID!
-user:: User!
+type User = {
+  id: number;
+  name: string;
+  email?: string;
+};
 ```
 
-**Emits:**
-
-```ts
-id: NonNullable<ID>
-user: NonNullable<User>
-```
+### Component Props: `@prop?:: T [:= default]`
 
-### In Function Signatures
+A `?` on a component prop name marks it optional in the generated
+constructor type. A `:=` default is purely a runtime initializer — it
+does NOT make the prop optional on its own. The three canonical shapes:
 
 ```coffee
-def findUser(id:: number):: User?
-  db.find(id) or undefined
-
-def getUser(id:: number):: User!
-  db.find(id) ?? throw new Error "Not found"
-
-def updateUser(id:: number, email:: string??):: boolean
-  ...
+export Counter = component
+  @value::  number              # required, no default
+  @step?::  number              # optional, no default
+  @label?:: string := "Count"   # optional with default
 ```
 
 **Emits:**
 
 ```ts
-function findUser(id: number): User | undefined { ... }
-function getUser(id: number): NonNullable<User> { ... }
-function updateUser(id: number, email: string | null | undefined): boolean { ... }
+export declare class Counter {
+  constructor(props: {
+    value: number;
+    step?: number;
+    label?: string;
+  });
+}
 ```
 
-### Optional Properties
+Writing `@prop:: T := V` (typed, defaulted, no `?`) declares a
+**required prop with a default** — the parent must still pass it. To
+make a prop optional, add `?` to the name.
 
-In structural types, `?` after the property name makes it optional (the
-property itself may be absent), distinct from value optionality:
+### Expressing Value Optionality
 
-```coffee
-type User =
-  id: number
-  name: string
-  email?: string      # Optional property — may be absent
-  phone?: string?     # Optional property that can also be undefined when present
-```
-
-**Emits:**
+When the **value** itself needs to permit `undefined` or `null`, write
+the union explicitly:
 
-```ts
-type User = {
-  id: number;
-  name: string;
-  email?: string;
-  phone?: string | undefined;
-};
+```coffee
+email::  string | undefined
+middle:: string | null | undefined
+id::     NonNullable<ID>
 ```
 
-### Key Distinction
-
-- `email?: string` — property may be absent
-- `email:: string?` — value may be undefined
-- `email?: string??` — property may be absent, value may be null or undefined
+This is the same form TypeScript uses, so the emitted DTS is a
+character-for-character match.
 
 ---
 
@@ -647,18 +616,20 @@ Types are optional and gradual:
 
 ### Project Level
 
-Configure via `rip.json` or the `"rip"` key in `package.json`:
+Configure via the `"rip"` key in `package.json`:
 
 ```json
 {
   "strict": true,
+  "checkAll": true,
   "exclude": ["vendor/**", "legacy/**"]
 }
 ```
 
 | Key | Purpose |
 |-----|--------|
-| `strict` | Enable strict mode for `rip check` (default: `false`) |
+| `strict` | Enable TS strict family for `rip check` (default: `false`) |
+| `checkAll` | Type-check every non-`@nocheck` `.rip` file, not just annotated ones (default: `false`) |
 | `exclude` | Glob patterns for files to skip during `rip check` |
 
 ### File Level
@@ -1153,9 +1124,10 @@ collection — the token itself is the answer:
 
 **Other special cases:**
 
-- **`?` / `??` / `!` suffixes**: These modify the type. When they appear
-  unspaced after an identifier at depth 0, they are part of the type:
-  `string?` → `"string?"`, `ID!` → `"ID!"`.
+- **`?` on names**: When `?` appears unspaced **before** a `::` annotation
+  on a parameter, field, or component prop name, the lexer marks the name
+  token as optional (`data.optional = true`). This is the sole optionality
+  marker — there are no `?` / `??` / `!` suffixes on type expressions.
 - **Generic `<>` vs comparison**: Inside a type context (after `::`), always
   treat `<` as opening a generic bracket. The type context is unambiguous
   because we are already inside a `::` collection.
@@ -1341,12 +1313,12 @@ syntax into standard TypeScript:
 | Rip syntax | TypeScript equivalent |
 |-----------|---------------------|
 | `::` | `:` (annotation sigil to type separator) |
-| `T?` | `T \| undefined` |
-| `T??` | `T \| null \| undefined` |
-| `T!` | `NonNullable<T>` |
+| `name?::` | `name?:` (optional parameter / field / prop) |
 
 Function type expressions use `=>` directly (same as TypeScript), so no
-arrow conversion is needed.
+arrow conversion is needed. Value-level optionality is written with
+explicit unions (`T | undefined`, `T | null`, `NonNullable<T>`) — there
+are no type-suffix operators.
 
 The function returns a `.d.ts` string. Declarations without type
 annotations are skipped — only annotated code appears in the output.
@@ -1774,29 +1746,28 @@ Type annotations never affect `let` vs `const` in `.js` output:
 
 ### Edge Cases
 
-#### Optionality Suffixes in Types
+#### Optionality Marker on Names
 
-The `?`, `??`, and `!` suffixes appear unspaced after the type name:
+A `?` placed unspaced **before** the `::` annotation on a parameter,
+field, or component prop name marks the name as optional:
 
 ```coffee
-email:: string?       # → type = "string?"
-middle:: string??     # → type = "string??"
-id:: ID!              # → type = "ID!"
-```
-
-In `rewriteTypes()`, when collecting type tokens, if the next token is `?`,
-`??`, or `!` and is **not spaced** from the previous token, include it as
-part of the type string.
+def fetch(url:: string, opts?:: RequestInit):: Response
+  ...
 
-The `emitTypes()` function expands these suffixes into standard TypeScript:
+type User =
+  id::    number
+  email?:: string   # optional field
+```
 
-| Rip suffix | TypeScript equivalent |
-|-----------|---------------------|
-| `T?` | `T \| undefined` |
-| `T??` | `T \| null \| undefined` |
-| `T!` | `NonNullable<T>` |
+In the lexer, when `?` appears immediately before `::`, it is stripped
+from the stream and `data.optional = true` is set on the preceding
+name token. `emitTypes()` reads that flag and emits `name?:` instead of
+`name:` in the generated TypeScript.
 
-See §1.6 for the full Rip-to-TypeScript conversion table (including `::` → `:`).
+Value-level optionality is expressed with explicit unions — there are
+no `T?` / `T??` / `T!` type-suffix operators. See §1.6 for the full
+Rip-to-TypeScript conversion table.
 
 #### File-Level Type Directives
 

package/docs/demo/README.md

@@ -6,7 +6,7 @@ The canonical "everything in one file" demo of the Rip App framework. Six compon
 
 ```
 docs/demo/
-├── components/
+├── routes/
 │   ├── _layout.rip   — root layout with nav + error boundary
 │   ├── index.rip     — Home page (file-based routing: / → index.rip)
 │   ├── counter.rip   — reactive state, := / ~> persistence to stash
@@ -22,7 +22,8 @@ docs/demo/
 ```bash
 bun run bundle:demo
 # wraps:
-# bun scripts/bundle-app.js docs/demo -o docs/example/index.json -t "Rip App Demo"
+# bun scripts/bundle-app.js docs/demo/routes --prefix _route --css docs/demo/css \
+#   -o docs/example/index.json -t "Rip App Demo"
 ```
 
 Output: `docs/example/index.json` — a single ~17 KB file containing every component's raw `.rip` source plus all CSS, ready to ship to any static host. The launcher at `docs/example/index.html` fetches it once and runs the whole app from memory: no bundler, no build step, no per-component network requests.
@@ -38,6 +39,6 @@ Then `<script type="text/rip">launch bundle: bundle</script>` mounts everything.
 
 ## Iterating
 
-Edit any `.rip` file under `components/`, then re-run `bun run bundle:demo` to refresh the bundled JSON. The launcher HTML at `docs/example/` will pick up the new bundle on next load.
+Edit any `.rip` file under `routes/`, then re-run `bun run bundle:demo` to refresh the bundled JSON. The launcher HTML at `docs/example/` will pick up the new bundle on next load.
 
 CSS is concatenated alphabetically by filename. Add `.css` files under `css/` to extend the design.