rip-lang 3.15.4 → 3.16.1

package/src/schema/runtime.generated.js

@@ -84,9 +84,21 @@ const __SCHEMA_RESERVED_STATIC = new Set([
   'parse','safe','ok','find','findMany','where','all','first','count','create','toSQL',
 ]);
 const __SCHEMA_RESERVED_INSTANCE = new Set([
-  'save','destroy','reload','ok','errors','toJSON',
+  'save','destroy','reload','ok','errors','toJSON','savedChanges','markDirty',
+  '_saving',
+]);
+// Implicit columns owned by directive-driven runtime behavior. Declaring
+// them as user fields would either shadow the runtime API (savedChanges /
+// markDirty in INSTANCE) or produce duplicate SET writes in the same
+// UPDATE statement when @timestamps / @softDelete bump them.
+const __SCHEMA_RESERVED_IMPLICIT = new Set([
+  'createdAt','updatedAt','deletedAt',
+]);
+const __SCHEMA_RESERVED = new Set([
+  ...__SCHEMA_RESERVED_STATIC,
+  ...__SCHEMA_RESERVED_INSTANCE,
+  ...__SCHEMA_RESERVED_IMPLICIT,
 ]);
-const __SCHEMA_RESERVED = new Set([...__SCHEMA_RESERVED_STATIC, ...__SCHEMA_RESERVED_INSTANCE]);
 
 const __schemaTypes = {
   string:   v => typeof v === 'string',
@@ -148,6 +160,63 @@ function __schemaSnake(s) { return s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLo
 
 function __schemaCamel(col) { return String(col).replace(/_([a-z])/g, (_, c) => c.toUpperCase()); }
 
+// Reject acronym-style camelCase like \`mdmID\`, \`userOrgID\`, or
+// \`XMLHttpRequest\`. Two consecutive uppercase letters break the
+// snake_case <-> camelCase bijection: \`mdmID\` would round-trip via
+// __schemaSnake to \`mdm_i_d\` and back via __schemaCamel to \`mdmID\`,
+// while a more natural snake_case spelling \`mdm_id\` round-trips to
+// \`mdmId\` (different identifier). Forcing canonical camelCase at
+// schema-definition time eliminates the entire class of edge case
+// in field-name resolution (markDirty, savedChanges keys, snake
+// aliases on hydrate). Same convention as Active Record / Java
+// Beans / Swift's "Acronyms in API names" guidance.
+//
+// Accepts: lowercase-first, alphanumeric body, no two consecutive
+// uppercase letters anywhere.
+//   ok:    name, mrn, firstName, mdmId, userOrgId, line2, a1b2
+//   bad:   ID, mdmID, userID, XMLHttpRequest, _foo, 1foo, foo_bar
+function __schemaValidateCanonicalName(name) {
+  if (typeof name !== 'string' || !/^[a-z][a-zA-Z0-9]*$/.test(name)) return false;
+  if (/[A-Z]{2,}/.test(name)) return false;
+  return true;
+}
+
+// Snapshot the current values of every persisted column on an instance:
+// the primary key, declared fields (from \`norm.fields\`), and \`belongsTo\`
+// FK columns (from \`norm.relations\`). Used by \`_hydrate\` and the INSERT
+// / UPDATE branches of \`__schemaSave\` (defined in the orm fragment,
+// which loads after this one) so that a later .save() can compare and
+// emit a SET only for columns the caller actually mutated. Lives in the
+// validate fragment because \`_hydrate\` owns it; the orm fragment is
+// the consumer.
+//
+// FK columns are keyed by their camelCase property name on the instance
+// (e.g. \`userId\`) — same convention the dirty Set, savedChanges Map,
+// and markDirty() resolver use.
+//
+// The primary key is captured so __schemaSave's UPDATE WHERE clause can
+// target the originally-loaded row even if \`inst[pk]\` is reassigned in
+// memory. PK never appears in the UPDATE SET; it's identity, not data.
+function __schemaSnapshot(norm, inst) {
+  const snap = Object.create(null);
+  snap[norm.primaryKey] = inst[norm.primaryKey];
+  for (const [n] of norm.fields) snap[n] = inst[n];
+  for (const [, rel] of norm.relations) {
+    if (rel.kind !== 'belongsTo') continue;
+    const fkCamel = __schemaCamel(rel.foreignKey);
+    snap[fkCamel] = inst[fkCamel];
+  }
+  return snap;
+}
+
+// SameValue-Zero: like ===, except NaN equals NaN. Used by the dirty
+// check so a persisted NaN doesn't trigger a wasted UPDATE on every
+// save. Distinguishes from Object.is by treating +0/-0 as equal, which
+// is the right semantics for SQL: the DB doesn't distinguish them.
+function __schemaSameValue(a, b) {
+  return a === b || (a !== a && b !== b);
+}
+
 const __SchemaRegistry = {
   _entries: new Map(),
   register(def) {
@@ -212,9 +281,24 @@ class __SchemaDef {
       if (this.kind === 'model' && __SCHEMA_RESERVED.has(n)) collision(n, 'reserved ORM name');
     };
 
+    const requireCanonicalName = (n, kindLabel) => {
+      if (!__schemaValidateCanonicalName(n)) {
+        throw new SchemaError(
+          [{
+            field: n,
+            error: 'invalid-name',
+            message: kindLabel + " name '" + n + "' is not canonical camelCase. " +
+              "Use a lowercase-first, alphanumeric identifier with no consecutive uppercase letters " +
+              "(e.g. 'mdmId' not 'mdmID'). This keeps snake_case <-> camelCase mapping unambiguous.",
+          }],
+          this.name, this.kind);
+      }
+    };
+
     for (const e of this._desc.entries) {
       switch (e.tag) {
         case 'field':
+          requireCanonicalName(e.name, 'field');
           noteCollision(e.name);
           fields.set(e.name, {
             name: e.name,
@@ -381,6 +465,20 @@ class __SchemaDef {
         Object.defineProperty(this, '_dirty', { value: new Set(), enumerable: false, writable: false, configurable: true });
         Object.defineProperty(this, '_persisted', { value: persisted === true, enumerable: false, writable: true, configurable: true });
         Object.defineProperty(this, '_snapshot', { value: null, enumerable: false, writable: true, configurable: true });
+        // Re-entry guard for save(): set true while a save is in flight,
+        // cleared in __schemaSave's finally. Throws on same-instance
+        // re-entry (typically from a hook accidentally calling save()
+        // on its own instance) instead of looping forever or racing the
+        // snapshot / savedChanges machinery.
+        Object.defineProperty(this, '_saving', { value: false, enumerable: false, writable: true, configurable: true });
+        // Mirrors Active Record's \`saved_changes\`: populated by save()
+        // with the field-level diff of the just-completed write. INSERT
+        // produces \`[null, newValue]\` per written field; UPDATE produces
+        // \`[oldValue, newValue]\` per changed field. An empty Map after a
+        // save() call means nothing was actually written. Reset to a
+        // fresh Map at the start of every save() so it always reflects
+        // the most recent save, never accumulates across calls.
+        Object.defineProperty(this, 'savedChanges', { value: new Map(), enumerable: false, writable: true, configurable: true });
         if (data && typeof data === 'object') {
           for (const k of fieldNames) {
             if (k in data && data[k] !== undefined) this[k] = data[k];
@@ -427,6 +525,43 @@ class __SchemaDef {
         enumerable: false, configurable: true, writable: true,
         value: function() { return def._validateFields(this, true); },
       });
+      // Public API for forcing a column into the next UPDATE when value
+      // identity can't detect the change — typically after an in-place
+      // mutation of an object-valued field (json, Date) where the JS
+      // reference is unchanged. Validates the field name against the
+      // schema so typos throw instead of silently no-op'ing, and is
+      // restricted to persisted instances since INSERT writes every
+      // non-null field anyway (silently doing nothing is a footgun).
+      Object.defineProperty(klass.prototype, 'markDirty', {
+        enumerable: false, configurable: true, writable: true,
+        value: function(name) {
+          if (!this._persisted) {
+            throw new Error(
+              "schema: markDirty('" + name + "') is only valid on persisted instances; INSERT writes every set field"
+            );
+          }
+          const n = __schemaCamel(name);
+          const norm = def._normalize();
+          // Accept declared fields and \`belongsTo\` FK column names
+          // (camelCase or snake_case input both resolve via __schemaCamel).
+          let valid = norm.fields.has(n);
+          if (!valid) {
+            for (const [, rel] of norm.relations) {
+              if (rel.kind === 'belongsTo' && __schemaCamel(rel.foreignKey) === n) {
+                valid = true;
+                break;
+              }
+            }
+          }
+          if (!valid) {
+            throw new Error(
+              "schema: markDirty('" + name + "') — '" + n + "' is not a declared field or belongs_to FK on " + (def.name || 'anon')
+            );
+          }
+          this._dirty.add(n);
+          return this;
+        },
+      });
       // toJSON mirrors the instance's own enumerable properties, which by
       // construction are: the primary key, declared fields, @timestamps
       // columns, @softDelete timestamp, @belongs_to FK columns, and any
@@ -486,6 +621,15 @@ class __SchemaDef {
     // Eager-derived fields re-run on hydrate — they're not persisted
     // and must be re-computed from the declared fields now present.
     this._applyEagerDerived(inst);
+    // Capture the as-loaded values so \`save()\` can emit a column-targeted
+    // UPDATE that only touches fields the caller actually mutated. Two
+    // reasons this matters: (a) avoids a pointless DB round-trip when the
+    // caller didn't change anything, and (b) sidesteps a hard DuckDB FK
+    // limitation — UPDATEs that touch indexed columns (PK / UNIQUE) on a
+    // row referenced by another table's FK are rejected even when the
+    // value isn't really changing. Writing only dirty columns keeps no-op
+    // saves out of the index path entirely.
+    inst._snapshot = __schemaSnapshot(this._normalize(), inst);
     return inst;
   }
 
@@ -887,7 +1031,7 @@ function __schemaTableName(model) { return __schemaPluralize(__schemaSnake(model
 function __schemaFkName(model) { return __schemaSnake(model) + '_id'; }
 `;
 export const SCHEMA_ORM_RUNTIME            = `function __schemaDefaultAdapter() {
-  const url = (typeof process !== 'undefined' && process.env?.DB_URL) || 'http://localhost:4213';
+  const url = (typeof process !== 'undefined' && process.env?.DB_URL) || 'http://localhost:9494';
   return {
     async query(sql, params) {
       const body = params && params.length ? { sql, params } : { sql };
@@ -994,6 +1138,21 @@ async function __schemaRunHook(def, inst, name) {
 }
 
 async function __schemaSave(def, inst) {
+  // Re-entry guard. Same-instance re-entry into save() — typically a
+  // hook on this very instance calling .save() on \`this\` — would race
+  // the snapshot / savedChanges machinery and almost certainly loop
+  // forever. Throw a clear error instead. The flag is per-instance, so
+  // independent instances saving in parallel are unaffected; sequential
+  // saves on the same instance work fine because \`finally\` clears it.
+  if (inst._saving) {
+    throw new Error(
+      "schema: save() re-entered on the same " + (def.name || 'instance') +
+      "; a hook on this instance called save() while a save was already in flight."
+    );
+  }
+  inst._saving = true;
+  try {
+
   const norm = def._normalize();
   const isNew = !inst._persisted;
 
@@ -1006,14 +1165,25 @@ async function __schemaSave(def, inst) {
   if (isNew) await __schemaRunHook(def, inst, 'beforeCreate');
   else       await __schemaRunHook(def, inst, 'beforeUpdate');
 
+  // Reset \`savedChanges\` at the start of every save so it always
+  // reflects the most recent write, never accumulates. Hooks running
+  // from this point until end-of-save read this Map; afterCreate /
+  // afterUpdate / afterSave see the just-completed write's diff.
+  inst.savedChanges = new Map();
+
   if (isNew) {
     const cols = [], placeholders = [], values = [];
+    // Track which persisted columns actually got written so savedChanges
+    // can record [null, newValue] entries below. Both declared fields
+    // and belongsTo FK columns count.
+    const writtenColumns = [];
     for (const [n, f] of norm.fields) {
       const v = inst[n];
       if (v == null) continue;
       cols.push('"' + __schemaSnake(n) + '"');
       placeholders.push('?');
       values.push(__schemaSerialize(v, f));
+      writtenColumns.push([n, v]);
     }
     // Include relation FKs. belongsTo FKs are camelCase properties on
     // the instance (e.g. organizationId for organization_id).
@@ -1025,6 +1195,7 @@ async function __schemaSave(def, inst) {
         cols.push('"' + rel.foreignKey + '"');
         placeholders.push('?');
         values.push(v);
+        writtenColumns.push([fkCamel, v]);
       }
     }
     const sql = 'INSERT INTO "' + norm.tableName + '" (' + cols.join(', ') + ') VALUES (' + placeholders.join(', ') + ') RETURNING *';
@@ -1053,19 +1224,148 @@ async function __schemaSave(def, inst) {
     // populated. Per-docs semantics ("materialize once, not reactive")
     // still hold — we're firing once, at end of construction, not on
     // subsequent mutations.
+    //
+    // Order matters here: snapshot the declared-field state BEFORE
+    // flipping \`_persisted\`, so a later save() can never see the
+    // combination "_persisted = true, _snapshot = null" (which would
+    // fall through to a full-row UPDATE and reintroduce the FK bug).
     def._applyEagerDerived(inst);
+    inst._snapshot = __schemaSnapshot(norm, inst);
     inst._persisted = true;
+    // Populate savedChanges with [null, newValue] per persisted column
+    // that was written (declared fields + belongsTo FKs). Mirrors
+    // Active Record: on a fresh INSERT every attribute "changed from
+    // nil to its new value". @timestamps columns get the same
+    // [null, newValue] treatment using the values RETURNING gave us
+    // — they were assigned on this INSERT, so they belong in the diff.
+    for (const [n, v] of writtenColumns) inst.savedChanges.set(n, [null, v]);
+    if (norm.timestamps) {
+      if (inst.createdAt != null) inst.savedChanges.set('createdAt', [null, inst.createdAt]);
+      if (inst.updatedAt != null) inst.savedChanges.set('updatedAt', [null, inst.updatedAt]);
+    }
   } else {
+    // Column-targeted UPDATE: only write fields that actually changed
+    // since hydrate / last save (snapshot comparison) or that the caller
+    // explicitly marked dirty via .markDirty(name) — escape hatch for
+    // in-place mutations of object-valued fields where === can't detect
+    // change. Two reasons this matters:
+    //   1. Skip a wasted DB round-trip when nothing changed.
+    //   2. DuckDB's foreign-key implementation rejects UPDATE statements
+    //      that touch indexed columns (PK / UNIQUE) on a row that is
+    //      referenced by another table's FK — even when the SET is a
+    //      no-op like "mrn = mrn". A full-row UPDATE on a parent table
+    //      with any child rows is therefore a hard error in DuckDB.
+    //      Writing only changed columns keeps no-op saves entirely off
+    //      the index path.
+    //
+    // We build \`nextSnap\` from the values we are about to write — BEFORE
+    // the await — and only install it on success. Doing this after the
+    // await would be unsafe under concurrent mutation: a write to the
+    // instance during the in-flight query would be captured into the
+    // post-await snapshot, mark itself "clean", and never be persisted.
+    //
+    // \`nextSnap\` is allocated lazily on the first changed field; the
+    // common no-op-save path keeps zero allocations.
     const sets = [], values = [];
+    const snap = inst._snapshot;
+    const dirty = inst._dirty;
+    const changes = inst.savedChanges;
+    let nextSnap = null;
+    // Declared fields.
     for (const [n, f] of norm.fields) {
+      const cur = inst[n];
+      const isDirty = dirty && dirty.has(n);
+      const changed = !snap || !Object.prototype.hasOwnProperty.call(snap, n) || !__schemaSameValue(snap[n], cur);
+      if (!isDirty && !changed) continue;
+      if (!nextSnap) nextSnap = Object.assign(Object.create(null), snap || {});
       sets.push('"' + __schemaSnake(n) + '" = ?');
-      values.push(__schemaSerialize(inst[n], f));
+      values.push(__schemaSerialize(cur, f));
+      nextSnap[n] = cur;
+      // Record [oldValue, newValue] for hook consumers / audit. Old
+      // value comes from the snapshot; if no snapshot existed (first
+      // save after a manually-constructed persisted instance) we
+      // record null as the old value, which is the best information
+      // we have.
+      const old = snap && Object.prototype.hasOwnProperty.call(snap, n) ? snap[n] : null;
+      changes.set(n, [old, cur]);
+    }
+    // belongsTo FK columns. Same dirty / snapshot / savedChanges
+    // machinery as declared fields, but the SQL column name is
+    // already snake_case (rel.foreignKey) and the value isn't passed
+    // through __schemaSerialize since FKs are scalar IDs.
+    for (const [, rel] of norm.relations) {
+      if (rel.kind !== 'belongsTo') continue;
+      const fkCamel = __schemaCamel(rel.foreignKey);
+      const cur = inst[fkCamel];
+      const isDirty = dirty && dirty.has(fkCamel);
+      const changed = !snap || !Object.prototype.hasOwnProperty.call(snap, fkCamel) || !__schemaSameValue(snap[fkCamel], cur);
+      if (!isDirty && !changed) continue;
+      if (!nextSnap) nextSnap = Object.assign(Object.create(null), snap || {});
+      sets.push('"' + rel.foreignKey + '" = ?');
+      values.push(cur);
+      nextSnap[fkCamel] = cur;
+      const old = snap && Object.prototype.hasOwnProperty.call(snap, fkCamel) ? snap[fkCamel] : null;
+      changes.set(fkCamel, [old, cur]);
+    }
+    // @timestamps: bump updated_at iff this UPDATE will actually emit
+    // SQL. The check sits between the diff loops and the write, so we
+    // only touch the column when sets has something else in it —
+    // never on a no-op save (which would defeat the column-targeted
+    // UPDATE optimization and reintroduce a wasted DB round-trip).
+    // The column itself isn't in \`_snapshot\` (we always overwrite it
+    // explicitly on every real write, never compare it for diffs),
+    // so we mirror the new value onto the instance and record it in
+    // savedChanges to mirror Active Record's saved_changes shape.
+    //
+    // \`oldTs\` is the in-memory value at this moment, which after
+    // hydrate is the DB-loaded timestamp and after a prior save in
+    // this session is the value we set then. If user code reassigns
+    // \`inst.updatedAt\` between saves, the recorded "old" reflects
+    // that reassignment, not what's actually in the DB. The implicit
+    // column isn't in the snapshot for the same reason it isn't in
+    // the diff loop: we always overwrite it on real writes.
+    //
+    // Declaring \`updatedAt\` as a regular field is rejected at schema
+    // definition (__SCHEMA_RESERVED_IMPLICIT) so we can't end up with
+    // duplicate "updated_at = ?" entries in \`sets\`.
+    if (norm.timestamps && sets.length > 0) {
+      const newTs = new Date().toISOString();
+      const oldTs = inst.updatedAt != null ? inst.updatedAt : null;
+      sets.push('"updated_at" = ?');
+      values.push(newTs);
+      inst.updatedAt = newTs;
+      changes.set('updatedAt', [oldTs, newTs]);
     }
     if (sets.length) {
+      // WHERE uses the *original* PK from the snapshot, not the live
+      // \`inst[pk]\` value. If user code reassigns the in-memory PK
+      // between hydrate and save, the UPDATE still targets the row
+      // that was actually loaded — mirrors Active Record, which
+      // ignores in-memory PK mutation when building the UPDATE.
+      // Falls back to \`inst[pk]\` only when no snapshot exists (e.g.
+      // a manually-constructed persisted instance), where there's
+      // no better information available. We log a warning in non-prod
+      // when the fallback fires, since "persisted instance with no
+      // snapshot" is almost always an accidental misuse pattern.
       const pk = norm.primaryKey;
-      values.push(inst[pk]);
+      let wherePk;
+      if (snap && snap[pk] != null) {
+        wherePk = snap[pk];
+      } else {
+        wherePk = inst[pk];
+        if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+          console.warn(
+            "[schema] " + (def.name || 'save()') + ": no _snapshot, falling back to inst." + pk +
+            " for the UPDATE WHERE clause. This usually means the instance was constructed " +
+            "with _persisted = true without going through hydrate(); the WHERE will target " +
+            "whatever inst." + pk + " happens to be at save time."
+          );
+        }
+      }
+      values.push(wherePk);
       const sql = 'UPDATE "' + norm.tableName + '" SET ' + sets.join(', ') + ' WHERE "' + pk + '" = ?';
       await __schemaAdapter.query(sql, values);
+      inst._snapshot = nextSnap;
     }
   }
   inst._dirty.clear();
@@ -1074,6 +1374,10 @@ async function __schemaSave(def, inst) {
   else       await __schemaRunHook(def, inst, 'afterUpdate');
   await __schemaRunHook(def, inst, 'afterSave');
   return inst;
+
+  } finally {
+    inst._saving = false;
+  }
 }
 
 async function __schemaDestroy(def, inst) {
@@ -1107,7 +1411,11 @@ __SchemaDef.prototype.find = async function (id) {
   const soft = norm.softDelete ? ' AND "deleted_at" IS NULL' : '';
   const sql = 'SELECT * FROM "' + norm.tableName + '" WHERE "' + norm.primaryKey + '" = ?' + soft + ' LIMIT 1';
   const res = await __schemaAdapter.query(sql, [id]);
-  if (!res.rows) return null;
+  // Harbor returns rowCount (not the legacy \`rows\` alias). Treat both
+  // as authoritative so the runtime works against any /sql adapter
+  // that has a row-count field, regardless of which name it uses.
+  const n = res.rowCount ?? res.rows;
+  if (!n || !res.data?.[0]) return null;
   return this._hydrate(res.columns, res.data[0]);
 };
 

package/src/schema/schema.js

@@ -541,7 +541,7 @@ function parseFieldedLine(kind, line, entries, ctx) {
         dname === 'one' || dname === 'many' || dname === 'mixin') {
       let t0 = argTokens[0];
       if (t0 && (t0[0] === 'IDENTIFIER' || t0[0] === 'PROPERTY')) {
-        let optional = t0.data?.predicate === true;
+        let optional = t0.data?.optional === true;
         if (!optional && argTokens[1]?.[0] === '?') optional = true;
         args = [{ target: t0[1], optional }];
       }
@@ -1468,9 +1468,9 @@ function compileDirectiveArgsLiteral(name, tokens) {
     }
     let target = t0[1];
     // `@belongs_to User?` tokenizes as IDENTIFIER "User" with
-    // data.predicate=true. A trailing `?` in a later token position is
+    // data.optional=true. A trailing `?` in a later token position is
     // also accepted for robustness.
-    let optional = t0.data?.predicate === true;
+    let optional = t0.data?.optional === true;
     let pos = 1;
     if (!optional && tokens[pos]?.[0] === '?') { optional = true; pos++; }
     let parts = [`target: ${JSON.stringify(target)}`];
@@ -1673,8 +1673,8 @@ function parseBodyTokens(bodyTokens) {
 function collectModifiers(identToken) {
   let mods = [];
   let d = identToken.data;
-  if (d?.await === true) mods.push('!');
-  if (d?.predicate === true) mods.push('?');
+  if (d?.bang === true) mods.push('!');
+  if (d?.optional === true) mods.push('?');
   return mods;
 }