objection 4.0.0-rc.3 → 4.0.0

package/lib/queryBuilder/graph/graphKeys.js

@@ -1,6 +1,7 @@
 import { nonStrictEquals } from '../../utils/objectUtils.js';
 import { ValidationErrorType } from '../../model/ValidationError.js';
 import { formatPath } from './GraphNode.js';
+import { RelationProperty } from '../../relations/RelationProperty.js';
 
 const UNRESOLVED = Symbol('unresolved');
 
@@ -16,16 +17,15 @@ export class GraphKeys {
   constructor(plan) {
     this.plan = plan;
     this.activeNodes = new Set(plan.activeNodes);
+    // The row of each node, and the rows by their keys:
     this.rows = new Map();
-    this.nodesByRow = new Map();
-    this.cells = new Map();
+    this.rowsByKey = new Map();
+    // The cells in their order:
+    this.cells = [];
     // The props that each node only reads, and that other nodes write:
     this.readProps = new Map();
     // The cells that each place sets or reads:
     this.placeCells = new Map();
-    // The rows that the graph inserts, and the ones that it inserted already:
-    this.insertRows = new Set();
-    this.insertedRows = new Set();
     // The nodes whose `#ref{}` values are resolved:
     this.resolvedNodes = new Set();
 
@@ -34,7 +34,7 @@ export class GraphKeys {
       const row = this._getRow(node);
 
       if (plan.actions.get(node) === 'insert') {
-        this.insertRows.add(row);
+        row.isInsert = true;
       }
     }
 
@@ -83,18 +83,20 @@ export class GraphKeys {
 
     // 4. The clears, with the nodes that clear the cells. The places of a node
     // read them as `null` if another node clears them:
-    this.clearingNodes = new Map();
     const addClearingNode = (row, prop, node) =>
       prop.props.forEach((_, i) => {
-        const key = this._getKey(row, prop, i);
-        this.clearingNodes.set(key, (this.clearingNodes.get(key) || new Set()).add(node));
+        const description = prop.propDescription(i);
+        row.clearingNodes.set(
+          description,
+          (row.clearingNodes.get(description) || new Set()).add(node),
+        );
       });
 
     for (const currentNode of plan.activeCurrentNodes) {
       const { relation, parent } = currentNode;
 
       if (relation?.keySide === 'related' && plan.actions.get(currentNode) === 'unrelate') {
-        addClearingNode(currentNode.rowKey, relation.relatedProp, parent.node);
+        addClearingNode(this._getRowByKey(currentNode.rowKey), relation.relatedProp, parent.node);
       }
     }
 
@@ -111,7 +113,7 @@ export class GraphKeys {
   // Bind the cells of the rows of the inserted `nodes` to their values.
   setInserted(nodes) {
     for (const node of nodes) {
-      this.insertedRows.add(this.rows.get(node));
+      this.rows.get(node).isInserted = true;
     }
   }
 
@@ -153,13 +155,25 @@ export class GraphKeys {
       .map(({ prop, index }) => prop.props[index]);
   }
 
+  // Return the cells of the row of `node` that the graph sets, unless `node`
+  // only reads them:
+  getSetCells(node) {
+    const row = this._getRow(node);
+    return [...(this.placeCells.get(node) || [])].filter(
+      (cell) =>
+        cell.row === row &&
+        cell.setNodes.size > 0 &&
+        !this.isOnlyRead(node, cell.prop.props[cell.index]),
+    );
+  }
+
   // Return true if a place other than the places of the row of `node` through
   // its BelongsToOne `relation` sets the key of the relation, e.g. the place
   // that moves the row.
   isSetByOtherPlaces(node, relation) {
     const row = this._getRow(node);
     return relation.ownerProp.props.some((_, i) =>
-      [...(this.cells.get(this._getKey(row, relation.ownerProp, i))?.placeNodes || [])].some(
+      [...(row.cells.get(relation.ownerProp.propDescription(i))?.placeNodes || [])].some(
         (other) => !(other.relation === relation && this._getRow(other.parent) === row),
       ),
     );
@@ -179,9 +193,7 @@ export class GraphKeys {
   getReadProps(node, prop) {
     return this._getCells(node, prop).map((cell) => {
       const values = this._getAnchorCells(cell.slot).map((anchor) =>
-        this.insertRows.has(anchor.row)
-          ? null
-          : (this._getStoredValue(anchor) ?? this._getAnchorValue(anchor)),
+        anchor.row.isInsert ? null : (this._getStoredValue(anchor) ?? this._getAnchorValue(anchor)),
       );
       const value = this._getSlotValue(cell);
       return values.length > 0
@@ -198,29 +210,47 @@ export class GraphKeys {
 
   // Return true if a place of `node` sets the key column `prop` of its row:
   isSet(node, prop, index) {
-    return !!this.cells.get(this._getKey(this._getRow(node), prop, index))?.setNodes.has(node);
+    const cell = this._getRow(node).cells.get(prop.propDescription(index));
+    return !!cell?.setNodes.has(node);
   }
 
-  // Return the nodes whose inserts or `#ref{}` values bind the slots of the
-  // cells that the place of `node` sets or reads.
+  // Return the nodes whose inserts, `#ref{}` values or changes bind the slots
+  // of the cells that the place of `node` sets or reads, and whether they
+  // change them.
   waitsFor(node) {
+    const { relation, parent } = node;
     const waits = [];
+    const addWaits = (cell, nodes, isKeyChange) => {
+      for (const other of nodes) {
+        if (this.rows.get(other) !== this.rows.get(node)) {
+          waits.push({ node: other, prop: cell.prop.props[cell.index], isKeyChange });
+        }
+      }
+    };
 
     for (const cell of this.placeCells.get(node) || []) {
       for (const anchorCell of this._getAnchorCells(cell.slot)) {
         const { row, prop, index } = anchorCell;
-        anchorCell.waitedNodes ??= this.nodesByRow
-          .get(row)
-          .filter(
-            (other) =>
-              (this.insertRows.has(row) && this.plan.actions.get(other) === 'insert') ||
-              this._hasReference(other, prop, index),
-          );
-
-        for (const other of anchorCell.waitedNodes) {
-          if (this.rows.get(other) !== this.rows.get(node)) {
-            waits.push({ node: other, prop: cell.prop.props[cell.index] });
-          }
+        anchorCell.waitedNodes ??= row.nodes.filter(
+          (other) =>
+            (row.isInsert && this.plan.actions.get(other) === 'insert') ||
+            this._hasReference(other, prop, index),
+        );
+        addWaits(cell, anchorCell.waitedNodes, false);
+
+        // Only the places that set a cell write the changes of its slot:
+        if (cell.setNodes.has(node)) {
+          addWaits(cell, [this._getChangingNode(anchorCell)].filter(Boolean), true);
+        }
+      }
+    }
+
+    // Join rows are inserted after all rows, but read the keys of their owners,
+    // which patches may change:
+    if (relation?.keySide === 'join') {
+      for (const cell of this._getCells(parent, relation.ownerProp)) {
+        for (const anchorCell of this._getAnchorCells(cell.slot)) {
+          addWaits(cell, [this._getChangingNode(anchorCell)].filter(Boolean), true);
         }
       }
     }
@@ -228,6 +258,44 @@ export class GraphKeys {
     return waits;
   }
 
+  // Return the patches and relates that change the column of another row that
+  // the `#ref{}` of `reference` copies into `node`, as for the keys:
+  getChangingNodes(node, { referencedNode, refPath }) {
+    const { modelClass } = referencedNode;
+    const [propName] = refPath;
+    // The cell of a key on the column, or one of its own:
+    const cell =
+      [...this._getRow(referencedNode).cells.values()].find(
+        ({ prop, index }) => prop.props[index] === propName && prop.isColumn(index),
+      ) ??
+      this._getCell(
+        referencedNode,
+        new RelationProperty(
+          `${modelClass.getTableName()}.${modelClass.propertyNameToColumnName(propName)}`,
+          () => modelClass,
+        ),
+        0,
+      );
+    return this._getAnchorCells(cell.slot)
+      .map((anchorCell) => this._getChangingNode(anchorCell))
+      .filter((other) => other && this.rows.get(other) !== this.rows.get(node));
+  }
+
+  // Return the patch or relate that changes the value of an anchor cell, or
+  // may change it, when its row isn't loaded. A foreign key may reference the
+  // cell, so the rows that read the new value wait for it (#428). Ids don't
+  // change, see `checkChangedIds()`, and rows without ids are found by the
+  // values that the graph gives them.
+  _getChangingNode(cell) {
+    const { writtenValue, writingNode } = this._getGivenValues(cell);
+    return writingNode &&
+      !cell.isId &&
+      (cell.row.isInsert || (writingNode.referencedNode || writingNode).obj.$hasId()) &&
+      !nonStrictEquals(writtenValue, this._getStoredValue(cell))
+      ? writingNode
+      : null;
+  }
+
   // The place of `node` gives `target` the key of `source`, for each column of
   // the relation:
   _addPlace(node, target, targetProp, source, sourceProp) {
@@ -244,8 +312,11 @@ export class GraphKeys {
         sourceCells[i].readerNodes.add(source);
 
         // A whole `#ref{}` value wins over the key of its place, also where the
-        // place lists the row again:
-        if (!this.wholeReferences.has(this._getPlaceKey(target, cell.prop.props[cell.index]))) {
+        // place lists the row again. Most graphs have none, so skip the keys:
+        if (
+          this.wholeReferences.size === 0 ||
+          !this.wholeReferences.has(this._getPlaceKey(target, cell.prop.props[cell.index]))
+        ) {
           cell.setNodes.add(target);
           cell.placeNodes.add(node);
           joinCells(cell, sourceCells[i]);
@@ -258,7 +329,7 @@ export class GraphKeys {
   // parent and the relation.
   _getPlaceKey(node, prop) {
     const { parent, relation } = node;
-    return `${this._getRow(node)}|${parent ? this._getRow(parent) : ''}|${relation?.name}|${prop}`;
+    return `${this._getRow(node).key}|${parent ? this._getRow(parent).key : ''}|${relation?.name}|${prop}`;
   }
 
   _addCells(node, cells) {
@@ -284,41 +355,49 @@ export class GraphKeys {
   _getRow(node) {
     let row = this.rows.get(node);
 
-    if (row === undefined) {
+    if (!row) {
       // A `#ref` model has the row of the model it refers to, and a new model
       // a row of its own:
       const { referencedNode } = node;
       row = referencedNode
         ? this._getRow(referencedNode)
-        : node.obj.$hasId()
-          ? node.rowKey
-          : `new:${this.rows.size}`;
+        : this._getRowByKey(node.obj.$hasId() ? node.rowKey : `new:${this.rows.size}`);
+      row.nodes.push(node);
       this.rows.set(node, row);
-
-      const nodes = this.nodesByRow.get(row);
-
-      if (nodes) {
-        nodes.push(node);
-      } else {
-        this.nodesByRow.set(row, [node]);
-      }
     }
 
     return row;
   }
 
-  _getKey(row, prop, index) {
-    return `${row}|${prop.propDescription(index)}`;
+  // The row with the `key` of its table and id, or of a new row:
+  _getRowByKey(key) {
+    let row = this.rowsByKey.get(key);
+
+    if (!row) {
+      row = {
+        key,
+        nodes: [],
+        // The cells by their props, and the nodes that clear them:
+        cells: new Map(),
+        clearingNodes: new Map(),
+        // Whether the graph inserts the row, and whether it is inserted:
+        isInsert: false,
+        isInserted: false,
+      };
+      this.rowsByKey.set(key, row);
+    }
+
+    return row;
   }
 
   _getCell(node, prop, index) {
     const row = this._getRow(node);
-    const key = this._getKey(row, prop, index);
-    let cell = this.cells.get(key);
+    const description = prop.propDescription(index);
+    let cell = row.cells.get(description);
 
     if (!cell) {
       cell = {
-        key,
+        description,
         row,
         node,
         prop,
@@ -330,7 +409,8 @@ export class GraphKeys {
         slot: null,
       };
       cell.slot = { cells: [cell] };
-      this.cells.set(key, cell);
+      this.cells.push(cell);
+      row.cells.set(description, cell);
     }
 
     return cell;
@@ -354,7 +434,7 @@ export class GraphKeys {
       const { actions, graphOptions } = this.plan;
       const givenValues = {};
 
-      for (const node of this.nodesByRow.get(row)) {
+      for (const node of row.nodes) {
         const action = actions.get(node);
 
         if (
@@ -376,8 +456,13 @@ export class GraphKeys {
             givenValues.value = value;
           }
 
-          if (givenValues.writtenValue === undefined && action !== 'insert') {
+          if (
+            givenValues.writtenValue === undefined &&
+            action !== 'insert' &&
+            value !== undefined
+          ) {
             givenValues.writtenValue = value;
+            givenValues.writingNode = node;
           }
 
           if (givenValues.writtenValue !== undefined) {
@@ -410,12 +495,12 @@ export class GraphKeys {
   // current value.
   _getAnchorValue(cell) {
     const { row, prop, index } = cell;
-    const nodes = this.nodesByRow.get(row);
+    const { nodes } = row;
     const [node] = nodes;
     const getValue = (obj) => (obj ? prop.getProp(obj, index) : undefined);
     const { writtenValue } = this._getGivenValues(cell);
 
-    if (this.insertRows.has(row)) {
+    if (row.isInsert) {
       const insertNode = nodes.find((node) => this.plan.actions.get(node) === 'insert');
       return writtenValue ?? getValue(insertNode.obj) ?? null;
     } else if (writtenValue !== undefined) {
@@ -439,7 +524,7 @@ export class GraphKeys {
   // Return true if an anchor cell waits for an insert or a `#ref{}` value:
   _isWaiting(cell) {
     return (
-      (this.insertRows.has(cell.row) && !this.insertedRows.has(cell.row)) ||
+      (cell.row.isInsert && !cell.row.isInserted) ||
       this._getGivenValues(cell).writtenValue === UNRESOLVED
     );
   }
@@ -450,14 +535,14 @@ export class GraphKeys {
   _getKnownKey(cell) {
     const { row, prop, index } = cell;
 
-    if (this.insertRows.has(row)) {
+    if (row.isInsert) {
       const { value } = this._getGivenValues(cell);
       return value === UNRESOLVED
         ? undefined
         : value !== undefined
           ? `=${value}`
           : cell.isId
-            ? row
+            ? row.key
             : undefined;
     } else {
       const value = this._isWaiting(cell) ? undefined : this._getAnchorValue(cell);
@@ -500,7 +585,7 @@ export class GraphKeys {
   _getStoredValue(cell) {
     const { row, prop, index } = cell;
 
-    for (const node of this.nodesByRow.get(row)) {
+    for (const node of row.nodes) {
       const value =
         !this.activeNodes.has(node) && prop.getProp(node.obj, index) !== undefined
           ? prop.getProp(node.obj, index)
@@ -516,7 +601,7 @@ export class GraphKeys {
 
   // Return true if another node than the ones that read `cell` clears it:
   _isCleared(cell) {
-    const clearingNodes = this.clearingNodes.get(cell.key);
+    const clearingNodes = cell.row.clearingNodes.get(cell.description);
     return (cell.isCleared ??=
       !!clearingNodes && [...clearingNodes].some((node) => !cell.readerNodes.has(node)));
   }
@@ -524,7 +609,7 @@ export class GraphKeys {
   // Throw for slots whose anchors, or whose rows without any, give different
   // values that are known before the writes.
   _checkSlots() {
-    const slots = new Set([...this.cells.values()].map((cell) => cell.slot));
+    const slots = new Set(this.cells.map((cell) => cell.slot));
 
     for (const slot of [...slots].filter(({ cells }) => cells.length > 1)) {
       const anchorCells = this._getAnchorCells(slot);

package/lib/queryBuilder/jsonDialects/JsonDialect.js

@@ -17,6 +17,12 @@ export class JsonDialect {
     return sql;
   }
 
+  // The value that the path updates of a column start from, an empty one where
+  // the column is NULL, as `set()` leaves NULL as it is.
+  setBase(sql, access) {
+    return `COALESCE(${sql}, '${access[0].type === 'array' ? '[]' : '{}'}')`;
+  }
+
   // Reference the bare column if there is no path, so that the database can use
   // its indexes.
   field(sql, access) {

package/lib/queryBuilder/operations/AsArrayOperation.js

@@ -0,0 +1,10 @@
+import { QueryBuilderOperation } from './QueryBuilderOperation.js';
+import { asArray } from '../../utils/objectUtils.js';
+
+// Wrap the result in an array in the order of the operations, so a `first()`
+// added after this unwraps it again.
+export class AsArrayOperation extends QueryBuilderOperation {
+  onAfter3(_, result) {
+    return asArray(result);
+  }
+}

package/lib/queryBuilder/operations/UpdateOperation.js

@@ -1,10 +1,11 @@
-import { isEmpty } from '../../utils/objectUtils.js';
+import { hasOwn, isEmpty } from '../../utils/objectUtils.js';
 import { QueryBuilderOperation } from './QueryBuilderOperation.js';
 import { StaticHookArguments } from '../StaticHookArguments.js';
 import { removeOverriddenValues } from '../../model/modelQueryProps.js';
 import {
   checkFieldExpressions,
   convertFieldExpressionsToRaw,
+  getJsonKeyPatch,
   removeFieldExpressions,
 } from './fieldExpressions.js';
 
@@ -65,14 +66,26 @@ export class UpdateOperation extends QueryBuilderOperation {
   }
 
   onBuildKnex(knexBuilder, builder) {
-    const json = this.model.$toDatabaseJson(builder);
-
-    if (this.modelOptions.patch) {
-      return knexBuilder.update(convertFieldExpressionsToRaw(builder, json));
-    } else {
+    if (!this.modelOptions.patch) {
       checkFieldExpressions(builder.modelClass(), this.model, 'update');
-      return knexBuilder.update(json);
     }
+
+    const json = this.model.$toDatabaseJson(builder);
+    const { jsonKeyPatches } = builder.internalOptions();
+
+    // The path updates are join expressions in column names, so they replace
+    // the mapped columns in the json:
+    for (const prop of jsonKeyPatches?.keys() || []) {
+      const patch = getJsonKeyPatch(this.model, prop, jsonKeyPatches);
+      const column = builder.modelClass().propertyNameToColumnName(prop);
+
+      if (patch && hasOwn(json, column)) {
+        delete json[column];
+        Object.assign(json, patch);
+      }
+    }
+
+    return knexBuilder.update(convertFieldExpressionsToRaw(builder, json));
   }
 
   async onAfter2(builder, numUpdated) {

package/lib/queryBuilder/operations/fieldExpressions.js

@@ -1,5 +1,5 @@
 import { ref } from '../ReferenceBuilder.js';
-import { isObject } from '../../utils/objectUtils.js';
+import { isObject, jsonEquals } from '../../utils/objectUtils.js';
 import { getFieldExpressionColumn } from '../../utils/parseFieldExpression.js';
 import { isKnexRaw, isKnexQueryBuilder } from '../../utils/knexUtils.js';
 import { getJsonDialect } from '../jsonDialects/index.js';
@@ -28,6 +28,15 @@ export function checkFieldExpressions(modelClass, model, operation) {
   }
 }
 
+// Return the path updates that write the keys that `upsertGraph()` gives the
+// json column `prop` of `model`, while the column holds nothing but these keys,
+// which keeps its other values (#415). A column that hooks change is written
+// whole (#488):
+export function getJsonKeyPatch(model, prop, jsonKeyPatches) {
+  const entry = jsonKeyPatches?.get(prop);
+  return entry && jsonEquals(model[prop], entry.keys) ? entry.patch : null;
+}
+
 // Field expressions only describe the writes into json columns, they aren't
 // properties of the models that the writes return:
 export function removeFieldExpressions(modelClass, model) {
@@ -48,7 +57,7 @@ export function convertFieldExpressionsToRaw(builder, json) {
 
     if (getFieldExpressionColumn(key, declaredColumns) !== null) {
       // 'col:attr' : ref('other:lol') is transformed to
-      // "col" : raw(`jsonb_set("table"."col", '{attr}', to_jsonb("other"#>'{lol}'), true)`)
+      // "col" : raw(`jsonb_set(COALESCE("table"."col", '{}'), '{attr}', to_jsonb("other"#>'{lol}'), true)`)
       // on Postgres, with the column qualified, as it is ambiguous with
       // `excluded` in merge().
       dialect.checkSupport();
@@ -82,9 +91,11 @@ export function convertFieldExpressionsToRaw(builder, json) {
         val = JSON.stringify(val);
       }
 
+      const { access } = parsed.parsedExpr;
+      const previous = convertedJson[parsed.column];
       convertedJson[parsed.column] = knex.raw(
-        dialect.set('??', parsed.parsedExpr.access, valuePlaceholder),
-        [convertedJson[parsed.column] || `${builder.tableRef()}.${parsed.column}`, val],
+        dialect.set(previous ? '??' : dialect.setBase('??', access), access, valuePlaceholder),
+        [previous || `${builder.tableRef()}.${parsed.column}`, val],
       );
     } else {
       convertedJson[key] = val;

package/lib/relations/RelationProperty.js

@@ -126,6 +126,17 @@ export class RelationProperty {
     return this._propSetters[index](obj, value);
   }
 
+  // Returns true if the index:th column is a whole column.
+  isColumn(index) {
+    return this._refs[index].isPlainColumnRef;
+  }
+
+  // Returns true if the index:th column is a key at the top level of a json
+  // column.
+  isJsonKey(index) {
+    return this._refs[index].parsedExpr.access.length === 1;
+  }
+
   // Returns an instance of ReferenceBuilder that points to the index:th
   // value of a row.
   ref(builder, index) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objection",
-  "version": "4.0.0-rc.3",
+  "version": "4.0.0",
   "description": "An SQL-friendly ORM for Node.js",
   "type": "module",
   "main": "lib/objection.js",
@@ -17,7 +17,7 @@
     "test": "pnpm eslint && vitest run && pnpm test:typings",
     "test:fast": "vitest run --bail 1",
     "test:watch": "vitest",
-    "test:typings": "tsc && tsc -p tests/ts/strict && tsc -p tests/bench/typings && prettier --check \"typings/**/*.ts\" \"tests/ts/**/*.ts\" \"tests/bench/typings/*.ts\" \"tests/bench/typings/app/*.ts\"",
+    "test:typings": "tsc && tsc -p tests/ts/strict && tsc -p tests/bench/typings && node tests/ts/completions.js && prettier --check \"typings/**/*.ts\" \"tests/ts/**/*.ts\" \"tests/bench/typings/*.ts\" \"tests/bench/typings/app/*.ts\"",
     "bench:typings": "node tests/bench/typings/bench.js",
     "db:up": "docker compose up -d --wait",
     "db:down": "docker compose --profile mssql down -v",
@@ -29,7 +29,7 @@
     "docs:preview": "vitepress preview doc"
   },
   "publishConfig": {
-    "tag": "next"
+    "tag": "latest"
   },
   "author": {
     "name": "Sami Koskimäki",
@@ -76,7 +76,13 @@
     "ajv-formats": "^3.0.1"
   },
   "peerDependencies": {
-    "knex": "^3.3.0"
+    "knex": "^3.3.0",
+    "typescript": ">=5.8"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.15.3",
@@ -91,6 +97,7 @@
     "sqlite3": "^6.0.1",
     "tedious": "^20.3.7",
     "typescript": "^7.0.0",
+    "typescript-5": "npm:typescript@5.8.3",
     "vitepress": "1.6.4",
     "vitest": "^4.1.11"
   }