objection 4.0.0-rc.3 → 4.0.0-rc.4

package/lib/queryBuilder/InternalOptions.js

@@ -6,6 +6,9 @@ export class InternalOptions {
     this.skipRelationFilter = false;
     // The join table extras that related updates write, all of them if null:
     this.joinTableExtras = null;
+    // The field expressions that `upsertGraph()` writes keys in json columns of
+    // updated rows with:
+    this.fieldExpressionKeys = [];
     this.debug = false;
     this.schema = undefined;
   }
@@ -18,6 +21,7 @@ export class InternalOptions {
     copy.isInternalQuery = this.isInternalQuery;
     copy.skipRelationFilter = this.skipRelationFilter;
     copy.joinTableExtras = this.joinTableExtras;
+    copy.fieldExpressionKeys = this.fieldExpressionKeys;
     copy.debug = this.debug;
     copy.schema = this.schema;
 

package/lib/queryBuilder/graph/GraphNode.js

@@ -191,6 +191,14 @@ export class GraphNode {
 
     for (const node of nodes) {
       if (node.isReference) {
+        // A `#ref` places its model in a relation, which a root doesn't have:
+        if (!node.parent) {
+          throw node.modelClass.createValidationError({
+            type: ValidationErrorType.InvalidGraph,
+            message: `the reference at ${formatPath(node.dataPathKey)} has no relation to place its model in`,
+          });
+        }
+
         node.referencedNode = getNode(node.reference);
       }
 

package/lib/queryBuilder/graph/GraphPlan.js

@@ -91,6 +91,19 @@ export class GraphPlan {
     );
   }
 
+  // Return true if the graph relates the row of `node` by the key of its
+  // BelongsToOneRelation alone, without an id or a reference.
+  isRelatedByKey(node) {
+    return (
+      this.actions.get(node) === 'relate' &&
+      node.relation.keySide === 'owner' &&
+      !node.hasId &&
+      !node.isReference &&
+      !node.isDbReference &&
+      node.propertyReferences.length === 0
+    );
+  }
+
   // Return true if the model of the `#ref` model `node` writes what `node`
   // would write to the row: The model is inserted, or it's written and its path
   // allows any write that the path of `node` allows.

package/lib/queryBuilder/graph/GraphSchedule.js

@@ -1,17 +1,22 @@
 import { hasOwnerKey, hasSameColumns, hasSameKey } from './graphKeys.js';
 import { groupBy } from '../../utils/objectUtils.js';
+import { ValidationErrorType } from '../../model/ValidationError.js';
+import { formatPath } from './GraphNode.js';
 
 // Order the writes of a planned graph in steps that keep keys and constraints
 // intact (#214), which `GraphWriter` writes:
 // 1. Move the rows that the graph relates to existing owners of HasMany and
 //    HasOne relations, as they may still sit below rows that the next step
-//    deletes. Rows that wait for inserts are related in step 3 or 4.
+//    deletes. Rows that wait for inserts or changed keys are related in step 3
+//    or 4.
 // 2. Remove rows that reference their owners, before the inserts that may need
 //    their unique keys.
 // 3. Insert the new rows in the order of their keys and references, then the
 //    keys deferred to break cycles and the join rows. Rows that move out of
 //    the slots of HasOneRelations that new rows go into are related in the
-//    same order, as the foreign key may be unique.
+//    same order, as the foreign key may be unique, and so are the patches and
+//    relates that change the keys that these rows read, as a foreign key may
+//    reference them (#428).
 // 4. Patch the changed rows, the other relates, and the keys of owners whose
 //    BelongsToOne rows were inserted, related or removed.
 // 5. Unrelate the rows that their own to-many relation on their own key leaves
@@ -25,7 +30,8 @@ export class GraphSchedule {
     this.plan = plan;
     this.keys = keys;
     // The nodes that each node waits for, through its keys, its references and
-    // the rows that move out of the slots that it goes into:
+    // the rows that move out of the slots that it goes into. `isKeyChange`
+    // marks the patches and relates that change the keys it reads:
     this.dependencies = createDependencies(plan, this.keys);
     // Dependencies that aren't waited for, to break cycles. Deferred keys are
     // written after the inserts:
@@ -36,9 +42,8 @@ export class GraphSchedule {
         ? []
         : plan.activeNodes.filter((node) => this._isMovedFirst(node)),
     );
-    // Relates that move the rows out of the slots of HasOneRelations that new
-    // rows go into, and that aren't moved first:
-    this.slotMovedNodes = this._getSlotMovedNodes();
+    // Relates and patches that aren't moved first but written in the inserts:
+    this.earlyNodes = this._getEarlyNodes();
     this.steps = this._planSteps();
   }
 
@@ -91,10 +96,9 @@ export class GraphSchedule {
           activeNodes.filter((node) => {
             const action = actions.get(node);
             return (
-              (action === 'patch' ||
-                (action === 'relate' &&
-                  !this.movedNodes.has(node) &&
-                  !this.slotMovedNodes.has(node))) &&
+              ['patch', 'relate'].includes(action) &&
+              !this.movedNodes.has(node) &&
+              !this.earlyNodes.has(node) &&
               // The row of a `#ref` model is written once, by its model:
               !this._isWrittenByModel(node)
             );
@@ -212,7 +216,25 @@ export class GraphSchedule {
           }
         }
       } else if (!breakCycle()) {
-        throw new Error('the object graph contains cyclic references');
+        // A patch that changes a key that the rows it waits for read can be
+        // written neither before nor after them:
+        const { node: changingNode } =
+          nodes
+            .filter((node) => !handledNodes.has(node))
+            .flatMap(getPendingDependencies)
+            .find(
+              ({ node, dependent, isKeyChange }) => isKeyChange && isBlockedBy(node, dependent),
+            ) || {};
+
+        if (changingNode) {
+          const { modelClass, dataPathKey } = changingNode;
+          throw modelClass.createValidationError({
+            type: ValidationErrorType.InvalidGraph,
+            message: `the graph changes a key of the ${modelClass.name} at ${formatPath(dataPathKey)} that rows read which it also waits for; write the key in a separate query first`,
+          });
+        } else {
+          throw new Error('the object graph contains cyclic references');
+        }
       }
     }
 
@@ -245,9 +267,10 @@ export class GraphSchedule {
 
   // Return true if the HasMany or HasOne relate of `node` moves its row to an
   // existing owner before the removals, see the steps above. `#ref` models may
-  // get their ids from the inserts, rows that wait for the inserts are written
-  // once they're known, and a relate into the slot of a HasOne row waits for
-  // the removal of that row, or its move, as its key may be unique.
+  // get their ids from the inserts, rows that wait for the inserts or for
+  // changed keys are written after them, and a relate into the slot of a HasOne
+  // row waits for the removal of that row, or its move, as its key may be
+  // unique.
   _isMovedFirst(node, visitedNodes = new Set()) {
     const { actions } = this.plan;
     visitedNodes.add(node);
@@ -257,7 +280,7 @@ export class GraphSchedule {
       !node.isReference &&
       node.relation.keySide === 'related' &&
       node.parent.existing &&
-      !this._waitsForInserts(node)
+      !this._waitsForWrites(node)
     ) {
       const slotNode = getSlotNode(node);
       const moverNode = getSlotMover(this.plan, node);
@@ -271,24 +294,32 @@ export class GraphSchedule {
     }
   }
 
-  // Find the relates that move the rows out of the slots of HasOneRelations
-  // that new rows go into, and that aren't moved first. They're related in the
-  // inserts, along with the relates that move the rows out of their own slots,
-  // as the foreign key may be unique.
-  _getSlotMovedNodes() {
+  // Find the relates and patches that are written in the inserts, as the rows
+  // written there wait for them: The relates that move the rows out of the
+  // slots of HasOneRelations that new rows go into, along with the relates that
+  // move the rows out of their own slots, as the foreign key may be unique, and
+  // the patches and relates that change the keys that these rows or join rows
+  // read, as a foreign key may reference them (#428).
+  _getEarlyNodes() {
+    const { actions } = this.plan;
     const nodes = new Set();
-    const addMoverNodes = (node) => {
-      for (const { node: moverNode, isSlotMove } of this.dependencies.get(node) || []) {
-        if (isSlotMove && !this.movedNodes.has(moverNode) && !nodes.has(moverNode)) {
-          nodes.add(moverNode);
-          addMoverNodes(moverNode);
+    const addEarlyNodes = (node) => {
+      for (const dependency of this.dependencies.get(node) || []) {
+        const { node: earlyNode, isSlotMove, isKeyChange } = dependency;
+        if (
+          (isSlotMove || isKeyChange) &&
+          !this.movedNodes.has(earlyNode) &&
+          !nodes.has(earlyNode)
+        ) {
+          nodes.add(earlyNode);
+          addEarlyNodes(earlyNode);
         }
       }
     };
 
     for (const node of this.plan.activeNodes) {
-      if (this.plan.actions.get(node) === 'insert') {
-        addMoverNodes(node);
+      if (actions.get(node) === 'insert' || (node.relation?.keySide === 'join' && !node.current)) {
+        addEarlyNodes(node);
       }
     }
 
@@ -317,19 +348,21 @@ export class GraphSchedule {
   }
 
   // Return true if `node` waits for the keys or references of inserted models,
-  // also through the models that it references (#356), and through the models
-  // that it waits for to get its keys.
-  _waitsForInserts(node, visitedNodes = new Set()) {
+  // or for keys that patches change (#428), also through the models that it
+  // references (#356), and through the models that it waits for to get its
+  // keys.
+  _waitsForWrites(node, visitedNodes = new Set()) {
     const { actions } = this.plan;
     visitedNodes.add(node);
     return (this.dependencies.get(node) || []).some((dependency) => {
-      const { node: dependencyNode, relation } = dependency;
+      const { node: dependencyNode, relation, isKeyWait, isKeyChange } = dependency;
       const referencedNode = dependencyNode.referencedNode || dependencyNode;
       return (
         actions.get(referencedNode) === 'insert' ||
-        ((!relation || dependency.isKeyWait) &&
+        isKeyChange ||
+        ((!relation || isKeyWait) &&
           !visitedNodes.has(referencedNode) &&
-          this._waitsForInserts(referencedNode, visitedNodes))
+          this._waitsForWrites(referencedNode, visitedNodes))
       );
     });
   }
@@ -458,18 +491,23 @@ function createDependencies(plan, keys) {
 
     // A place waits for the inserts and `#ref{}` values that bind the slots of
     // its keys. A dependency on the same row through the same key becomes such
-    // a wait, and stays deferrable to break cycles. The other waits aren't:
-    for (const { node: waitedNode, prop } of keys.waitsFor(node)) {
+    // a wait, and stays deferrable to break cycles. The other waits aren't. A
+    // key change is waited for at the node that writes it, not at a `#ref`
+    // model of its row, which writes nothing:
+    for (const { node: waitedNode, prop, isKeyChange } of keys.waitsFor(node)) {
       const dependency = (dependencies.get(node) || []).find(
         (dependency) =>
-          getRow(dependency.node) === getRow(waitedNode) &&
+          (isKeyChange
+            ? dependency.node === waitedNode
+            : getRow(dependency.node) === getRow(waitedNode)) &&
           (!dependency.relation || getKeyProps(dependency, node).includes(prop)),
       );
 
       if (dependency) {
         dependency.isKeyWait = true;
+        dependency.isKeyChange ||= isKeyChange;
       } else {
-        addDependency(node, { node: waitedNode, isKeyWait: true });
+        addDependency(node, { node: waitedNode, isKeyWait: true, isKeyChange });
       }
     }
 

package/lib/queryBuilder/graph/GraphUpsert.js

@@ -9,6 +9,7 @@ import {
   checkChangedIds,
   checkGraph,
   checkJoinTables,
+  checkKeyRelates,
   checkMissingModels,
   checkPlacements,
   checkReadKeys,
@@ -100,6 +101,7 @@ export class GraphUpsert {
       }
 
       checkChangedIds(builder, plan);
+      checkKeyRelates(builder, plan);
       checkReferences(builder, plan);
       checkJoinTables(builder, plan);
       await new GraphWriter(new GraphSchedule(plan, keys)).write(builder);

package/lib/queryBuilder/graph/GraphWriter.js

@@ -2,6 +2,7 @@ import { getModel } from '../../model/getModel.js';
 import { restoreOmitFromDatabaseJson } from '../../model/modelUtils.js';
 import { valuesKey } from '../../model/modelValues.js';
 import { UpdateOperation } from '../operations/UpdateOperation.js';
+import { removeFieldExpressions } from '../operations/fieldExpressions.js';
 import { getMaxRows, hasBatchInsert } from '../../utils/knexUtils.js';
 import { isInternalProp } from '../../utils/internalPropUtils.js';
 import {
@@ -125,14 +126,15 @@ export class GraphWriter {
     await promiseMap(batches, (batch) => this._insertBatch(builder, batch), {
       concurrency: getConcurrency(builder, nodes),
     });
-    await this._patch(
-      builder,
-      nodes.filter((node) => this.schedule.slotMovedNodes.has(node)),
-    );
 
     for (const node of references) {
       resolveDependencies(this.schedule, node);
     }
+
+    await this._patch(
+      builder,
+      [...nodes, ...references].filter((node) => this.schedule.earlyNodes.has(node)),
+    );
   }
 
   async _insertBatch(builder, nodes) {
@@ -275,6 +277,8 @@ export class GraphWriter {
     } finally {
       for (const [node, props] of omittedProps) {
         restoreOmitFromDatabaseJson(node.obj, props);
+        // The keys of `setKeyPaths()` stay where a hook resolves the patch:
+        removeFieldExpressions(node.modelClass, node.obj);
       }
     }
   }
@@ -284,6 +288,12 @@ export class GraphWriter {
   _preparePatch(builder, node) {
     const { referencedNode } = node;
 
+    // A row that the graph relates by its key alone isn't looked up, its key is
+    // only written to its owner:
+    if (this.plan.isRelatedByKey(node)) {
+      return null;
+    }
+
     // The props that the graph fills into the model of a `#ref` model are only
     // final now:
     if (referencedNode) {
@@ -304,6 +314,8 @@ export class GraphWriter {
         ? node.relation.relatedProp.props
         : []),
     ];
+    // The keys in json paths that the write sets or clears:
+    let pathKeys = new Map();
     // Changing the id never makes sense with `upsertGraph()`. A many-to-many
     // `#ref` model whose model writes its row only writes its join row:
     const idProps = node.modelClass.getIdPropertyArray();
@@ -311,11 +323,15 @@ export class GraphWriter {
       !!referencedNode && node.relation.keySide === 'join' && this.plan.isCoveredByModel(node);
     const isWritable = (prop) =>
       !idProps.includes(prop) &&
+      !pathKeys.has(prop) &&
       !this.schedule.keys.isOnlyRead(node, prop) &&
       (!isJoinRowOnly || node.relation.joinTableExtras.some((extra) => extra.aliasProp === prop));
 
     const getPropsToUpdate = (changedProps) =>
-      (shouldPatch || shouldUpdate ? changedProps : keyProps).filter(isWritable);
+      (shouldPatch || shouldUpdate
+        ? changedProps
+        : keyProps.flatMap((prop) => pathKeys.get(prop) || prop)
+      ).filter(isWritable);
 
     // Leave out the props that don't change, and return true if any do.
     const handleUpdate = ({ changedProps, unchangedProps } = this._findChanges(node)) => {
@@ -335,21 +351,43 @@ export class GraphWriter {
     // what to update. Otherwise, the hook may still change the model, and we
     // check again after it runs, but only if the model has props to update, as
     // relates are no updates (#2233, #2605).
-    const changes = this._findChanges(node);
-    const propsToUpdate = getPropsToUpdate(changes.changedProps);
     const hasBeforeUpdate = hasHook(node.obj, 'beforeUpdate');
 
-    if (propsToUpdate.length === 0) {
+    let changes = this._findChanges(node);
+
+    if (getPropsToUpdate(changes.changedProps).length === 0) {
       return null;
-    } else if (!hasBeforeUpdate) {
-      handleUpdate(changes);
     }
 
     node.obj.$validate(null, {
       dataPath: node.dataPathKey,
-      patch: shouldPatch || !shouldUpdate,
+      patch: !shouldUpdate,
     });
 
+    // Write the keys in json columns as path updates where their column holds
+    // nothing else, which keeps its other values (#415). After the validation,
+    // as `update()` validates them as properties of their own:
+    pathKeys = setKeyPaths(node, [
+      ...this.schedule.keys.getSetCells(node),
+      ...this.plan
+        .getRemovedOwnerRelations(node)
+        .flatMap(({ ownerProp }) =>
+          ownerProp.props.map((_, index) => ({ prop: ownerProp, index })),
+        ),
+    ]);
+
+    if (pathKeys.size > 0) {
+      changes = this._findChanges(node);
+    }
+
+    const propsToUpdate = getPropsToUpdate(changes.changedProps);
+
+    if (propsToUpdate.length === 0) {
+      return null;
+    } else if (!hasBeforeUpdate) {
+      handleUpdate(changes);
+    }
+
     // Rows that their owners relate by their keys can't be found through the
     // relation until the owners are patched, so they're patched directly.
     const { relation } = node;
@@ -360,17 +398,26 @@ export class GraphWriter {
 
     return {
       node,
-      shouldPatch,
+      shouldUpdate,
       hasBeforeUpdate,
       handleUpdate,
       propsToUpdate,
+      fieldExpressionKeys: [...pathKeys.values()].flat(),
       isPatchedThroughRelation,
     };
   }
 
   _writePatch(
     builder,
-    { node, shouldPatch, hasBeforeUpdate, handleUpdate, propsToUpdate, isPatchedThroughRelation },
+    {
+      node,
+      shouldUpdate,
+      hasBeforeUpdate,
+      handleUpdate,
+      propsToUpdate,
+      fieldExpressionKeys,
+      isPatchedThroughRelation,
+    },
   ) {
     const query = (
       isPatchedThroughRelation
@@ -392,6 +439,8 @@ export class GraphWriter {
         // Join rows are patched with the extras among the props to update. The
         // extras of new join rows are written with them, see `_findChanges()`:
         joinTableExtras: node.relation?.keySide === 'join' && !node.current ? [] : propsToUpdate,
+        // The keys in json columns, also in updates:
+        fieldExpressionKeys,
       })
       .copyFrom(builder, isReturningAll);
 
@@ -405,7 +454,8 @@ export class GraphWriter {
       });
     }
 
-    return (shouldPatch ? query.patch(node.obj) : query.update(node.obj))
+    // Writes of only the keys under `noUpdate` are patches too:
+    return (shouldUpdate ? query.update(node.obj) : query.patch(node.obj))
       .runAfter(async (result, query) => {
         if (isObject(result) && result.$isObjectionModel) {
           // Handle `returning('*')`.
@@ -554,7 +604,7 @@ function resolveDependencies(schedule, node) {
 // Copy the keys and `#ref{}` values that `node` waits for into its model,
 // after those that the graph fills into the models that it reads them from,
 // e.g. the new key of an owner whose BelongsToOne row is replaced. Rows that
-// move first only wait for rows that exist, see `GraphSchedule#_waitsForInserts()`.
+// move first only wait for rows that exist, see `GraphSchedule#_waitsForWrites()`.
 function resolveFilledDependencies(schedule, node, visitedNodes = new Set()) {
   visitedNodes.add(node);
 
@@ -746,6 +796,40 @@ async function fetchGeneratedKeys(builder, modelClass, nodes) {
   }
 }
 
+// Add the changed keys of `cells` at the top level of json columns to `node` as
+// field expressions where their column holds nothing but these keys, and return
+// them by column. PostgreSQL and MySQL can't write nested paths whose parents
+// are missing, so their columns are written whole.
+function setKeyPaths(node, cells) {
+  const keysByColumn = new Map();
+  const pathCells = cells.filter(({ prop, index }) => prop.isJsonKey(index));
+
+  for (const [column, columnCells] of groupBy(pathCells, ({ prop, index }) => prop.props[index])) {
+    const keys = {};
+
+    for (const { prop, index } of columnCells) {
+      prop.setProp(keys, index, prop.getProp(node.obj, index));
+    }
+
+    if (jsonEquals(node.obj[column], keys[column])) {
+      const patch = {};
+
+      for (const { prop, index } of columnCells) {
+        const value = prop.getProp(node.obj, index);
+
+        if (!node.current || !nonStrictEquals(prop.getProp(node.current.obj, index), value)) {
+          prop.patch(patch, index, value);
+        }
+      }
+
+      Object.assign(node.obj, patch);
+      keysByColumn.set(column, Object.keys(patch));
+    }
+  }
+
+  return keysByColumn;
+}
+
 function hasOwnerKeyArray(relation) {
   return relation.keySide === 'owner' && !relation.isOneToOne();
 }

package/lib/queryBuilder/graph/graphChecks.js

@@ -223,7 +223,7 @@ export function checkPlacements(builder, nodes) {
     } else if (!nonStrictEquals(other.value, value)) {
       throw builder.modelClass().createValidationError({
         type: ValidationErrorType.InvalidGraph,
-        message: `the graph gives ${prop} of one ${name} two values, at ${formatPath(other.path)} and at ${formatPath(path)}`,
+        message: `the graph gives ${prop} of one ${name} two values, at ${formatPath(other.path())} and at ${formatPath(path())}`,
       });
     }
   };
@@ -243,7 +243,8 @@ export function checkPlacements(builder, nodes) {
         .map(([cols, rowId]) => `${cols}=${rowId}`),
     ].join(':');
 
-  const getPath = (node, ...keys) => [node.dataPathKey, ...keys].filter(Boolean).join('.');
+  // The data paths are only built for the errors:
+  const getPath = (node, key) => () => [node.dataPathKey, key].filter(Boolean).join('.');
   const isSlot = (relation) => relation.keySide === 'related' && relation.isOneToOne();
 
   // The props that the models give, except for the ids and the keys that the
@@ -405,7 +406,7 @@ export function checkPlacements(builder, nodes) {
       const other = rows.get(otherRowId).get(relatedProp.props[0]);
       throw builder.modelClass().createValidationError({
         type: ValidationErrorType.InvalidGraph,
-        message: `the graph puts two ${relatedModelClass.name} rows in ${relation.name} of one ${owner.modelClass.name}, at ${formatPath(path)} and at ${formatPath(other.path)}`,
+        message: `the graph puts two ${relatedModelClass.name} rows in ${relation.name} of one ${owner.modelClass.name}, at ${formatPath(path())} and at ${formatPath(other.path())}`,
       });
     }
   }
@@ -444,6 +445,42 @@ export function checkReferences(builder, plan) {
   }
 }
 
+// A model that the graph relates by the key of its BelongsToOneRelation alone
+// isn't looked up: only its key is written to its owner. So it can't give other
+// props, unless they aren't written, relations or values that others refer to.
+export function checkKeyRelates(builder, plan) {
+  const { graphOptions } = plan;
+
+  for (const node of plan.activeNodes.filter((node) => plan.isRelatedByKey(node))) {
+    const { modelClass, relation, obj } = node;
+    const relationNames = modelClass.getRelationNames();
+    const idProps = modelClass.getIdPropertyArray();
+    const isWritten = graphOptions.shouldPatch(node) || graphOptions.shouldUpdate(node);
+    const name = Object.keys(obj).find((key) => {
+      const value = obj[key];
+      return (
+        value !== undefined &&
+        !isInternalProp(key) &&
+        !relation.relatedProp.props.includes(key) &&
+        !(value === null && idProps.includes(key)) &&
+        (relationNames.includes(key) || isWritten)
+      );
+    });
+    const isReferenced =
+      node.propertyReferencingNodes.length > 0 ||
+      plan.nodes.some((other) => other.referencedNode === node);
+
+    if (name || isReferenced) {
+      throw builder.modelClass().createValidationError({
+        type: ValidationErrorType.InvalidGraph,
+        message: `the ${modelClass.name} at ${formatPath(node.dataPathKey)} is related by its key alone, so ${
+          name ? `its ${name} can't be written` : "it can't be referenced"
+        }`,
+      });
+    }
+  }
+}
+
 // A `#ref{}` waits for the model it reads if the value only exists once that
 // model is written. These waits follow from the graph alone, so their cycles
 // are found before the first write.

package/lib/queryBuilder/graph/graphKeys.js

@@ -18,7 +18,9 @@ export class GraphKeys {
     this.activeNodes = new Set(plan.activeNodes);
     this.rows = new Map();
     this.nodesByRow = new Map();
-    this.cells = new Map();
+    // The cells in their order, and those of each row by their props:
+    this.cells = [];
+    this.cellsByRow = new Map();
     // The props that each node only reads, and that other nodes write:
     this.readProps = new Map();
     // The cells that each place sets or reads:
@@ -153,13 +155,26 @@ 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);
+    const cells = this.cellsByRow.get(row);
     return relation.ownerProp.props.some((_, i) =>
-      [...(this.cells.get(this._getKey(row, relation.ownerProp, i))?.placeNodes || [])].some(
+      [...(cells?.get(relation.ownerProp.propDescription(i))?.placeNodes || [])].some(
         (other) => !(other.relation === relation && this._getRow(other.parent) === row),
       ),
     );
@@ -198,13 +213,23 @@ 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.cellsByRow.get(this._getRow(node))?.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)) {
@@ -216,11 +241,21 @@ export class GraphKeys {
               (this.insertRows.has(row) && this.plan.actions.get(other) === 'insert') ||
               this._hasReference(other, prop, index),
           );
+        addWaits(cell, anchorCell.waitedNodes, false);
 
-        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] });
-          }
+        // 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 +263,21 @@ export class GraphKeys {
     return waits;
   }
 
+  // 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 &&
+      (this.insertRows.has(cell.row) || (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 +294,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]);
@@ -313,12 +366,19 @@ export class GraphKeys {
 
   _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 cells = this.cellsByRow.get(row);
+
+    if (!cells) {
+      cells = new Map();
+      this.cellsByRow.set(row, cells);
+    }
+
+    let cell = cells.get(description);
 
     if (!cell) {
       cell = {
-        key,
+        key: this._getKey(row, prop, index),
         row,
         node,
         prop,
@@ -330,7 +390,8 @@ export class GraphKeys {
         slot: null,
       };
       cell.slot = { cells: [cell] };
-      this.cells.set(key, cell);
+      this.cells.push(cell);
+      cells.set(description, cell);
     }
 
     return cell;
@@ -376,8 +437,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) {
@@ -524,7 +590,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/UpdateOperation.js

@@ -70,8 +70,11 @@ export class UpdateOperation extends QueryBuilderOperation {
     if (this.modelOptions.patch) {
       return knexBuilder.update(convertFieldExpressionsToRaw(builder, json));
     } else {
-      checkFieldExpressions(builder.modelClass(), this.model, 'update');
-      return knexBuilder.update(json);
+      const { fieldExpressionKeys } = builder.internalOptions();
+      checkFieldExpressions(builder.modelClass(), this.model, 'update', fieldExpressionKeys);
+      return knexBuilder.update(
+        fieldExpressionKeys.length > 0 ? convertFieldExpressionsToRaw(builder, json) : json,
+      );
     }
   }
 

package/lib/queryBuilder/operations/fieldExpressions.js

@@ -7,13 +7,14 @@ import { ValidationErrorType } from '../../model/ValidationError.js';
 import { getQueryPropKeys } from '../../model/modelQueryProps.js';
 
 // Inserts and updates write whole values, so they can't write into json
-// columns with field expressions like `'meta:color'`. Keys with a ':' that don't
-// parse as field expressions are columns, as in the query properties.
-export function checkFieldExpressions(modelClass, model, operation) {
+// columns with field expressions like `'meta:color'`, except for the
+// `allowedKeys` of internal writes. Keys with a ':' that don't parse as field
+// expressions are columns, as in the query properties.
+export function checkFieldExpressions(modelClass, model, operation, allowedKeys = []) {
   const keys = getFieldExpressionKeys(modelClass, [
     ...Object.keys(model),
     ...getQueryPropKeys(model),
-  ]);
+  ]).filter((key) => !allowedKeys.includes(key));
 
   if (keys.length > 0) {
     throw modelClass.createValidationError({
@@ -48,7 +49,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 +83,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,12 @@ export class RelationProperty {
     return this._propSetters[index](obj, value);
   }
 
+  // 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-rc.4",
   "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",
@@ -91,6 +91,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"
   }

package/typings/objection/index.d.ts

@@ -475,7 +475,7 @@ export type ItemType<T> = T extends Array<unknown> ? T[number] : T;
  * Type for keys of non-function properties of T.
  */
 export type NonFunctionPropertyNames<T> = {
-  [K in keyof T]: T[K] extends Function ? never : K;
+  [K in keyof T]-?: T[K] extends Function ? never : K;
 }[keyof T];
 
 // The type-only members of models, which aren't data, also the keys of the
@@ -540,7 +540,7 @@ export type PartialModelObject<T extends Model> = {
         ? I[] | PartialModelObject<I>[]
         : Expression<T[K]>
       : NonNullable<T[K]> extends Model
-        ? Expression<T[K]> | PartialModelObject<NonNullable<T[K]>> // nullable to-one relations
+        ? Expression<T[K]> | PartialModelObject<NonNullable<T[K]>> // Nullable to-one relations
         : Expression<T[K]>;
 };
 
@@ -591,7 +591,7 @@ export type GraphParameters = {
 export type PartialModelGraph<M, T = M & GraphParameters> = T extends any
   ? {
       [K in DataPropertyNames<T>]?: null extends T[K]
-        ? PartialModelGraphField<NonNullable<T[K]>> | null // handle nullable BelongsToOneRelations
+        ? PartialModelGraphField<NonNullable<T[K]>> | null // Strip null to recognize to-one relations
         : PartialModelGraphField<T[K]>;
     }
   : never;
@@ -635,9 +635,10 @@ export type OptionalInsertPropertyNames<M> = {
 export type InsertablePropertyNames<M> = Exclude<DataPropertyNames<M>, RelationPropertyNames<M>>;
 
 /**
- * The data to insert a model M with `insert()`. Unlike `PartialModelObject`,
- * all properties are required except optional, nullable and `Generated`
- * ones. Relation properties are left out.
+ * The complete data of a new row of model M, to check what is passed to
+ * `insert()`, which itself takes any subset of the properties. Unlike
+ * `PartialModelObject`, all properties are required except optional, nullable
+ * and `Generated` ones. Relation properties are left out.
  */
 export type Insertable<M extends Model> = {
   [K in Exclude<InsertablePropertyNames<M>, OptionalInsertPropertyNames<M>>]: Expression<M[K]>;
@@ -646,9 +647,9 @@ export type Insertable<M extends Model> = {
 };
 
 /**
- * Like `Insertable`, but for `insertGraph()`: relation properties are
- * optional and hold the insertable graphs of the related models, or
- * references to existing ones through `#dbRef` or `#ref`.
+ * Like `Insertable`, but for graphs passed to `insertGraph()`: relation
+ * properties are optional and hold the insertable graphs of the related
+ * models, or references to existing ones through `#dbRef` or `#ref`.
  */
 export type InsertableGraph<M extends Model> = Insertable<M> &
   Omit<GraphParameters, '#dbRef' | '#ref'> & {
@@ -667,38 +668,15 @@ export type InsertableGraphField<F> =
 /**
  * Extracts the property names (excluding relations) of a model class.
  */
-export type ModelProps<T extends Model> = Exclude<
-  {
-    [K in keyof T]?: Defined<T[K]> extends Model
-      ? never
-      : Defined<T[K]> extends Array<infer I>
-        ? I extends Model
-          ? never
-          : K
-        : T[K] extends Function
-          ? never
-          : K;
-  }[keyof T],
-  undefined | ModelTypeMembers
->;
+export type ModelProps<T extends Model> = InsertablePropertyNames<T>;
 
 /**
- * Extracts the relation names of the a model class.
+ * Extracts the relation names of a model class.
  */
-export type ModelRelations<T extends Model> = Defined<
-  {
-    [K in keyof T]?: Defined<T[K]> extends Model
-      ? K
-      : Defined<T[K]> extends Array<infer I>
-        ? I extends Model
-          ? K
-          : never
-        : never;
-  }[keyof T]
->;
+export type ModelRelations<T extends Model> = RelationPropertyNames<T>;
 
 /**
- * Given a model property type, returns a query builer type of
+ * Given a model property type, returns a query builder type of the
  * correct kind if the property is a model or a model array. Queries for
  * to-one relations resolve to `undefined` when there's no related row.
  */
@@ -760,6 +738,18 @@ type Rebind<
  */
 export type ExtraType<T extends { ExtraType: any }> = T['ExtraType'];
 
+/**
+ * The extra type of queries in strict mode: the model class C that started the
+ * query, e.g. with `Person.query()`, and the modifiers P registered with
+ * `modifiers()`, to check the names of modifiers, and the id I of the class,
+ * for `findById()` and the other `*ById()` methods.
+ */
+export interface QueryExtra<C = unknown, P = unknown, I = MaybeCompositeId> {
+  modelClass: C;
+  registered: P;
+  id: I;
+}
+
 type WithExtra<QB extends AnyQueryBuilder, X> = Rebind<QB, ModelType<QB>, ResultType<QB>, X>;
 
 // The narrowed query builders of `withGraph*()` start without the extra type
@@ -792,15 +782,16 @@ export type NumberQueryBuilder<QB extends AnyQueryBuilder> = QB['~number'];
  */
 export type PageQueryBuilder<QB extends AnyQueryBuilder> = QB['~page'];
 
-// Strict mode checks the column names and values of queries against the
-// models. Augment `TypeConfig` to opt in:
-//
-//   declare module 'objection' {
-//     interface TypeConfig {
-//       strict: true;
-//     }
-//   }
-
+/**
+ * Strict mode checks the column names and values of queries against the
+ * models. Augment `TypeConfig` to opt in:
+ *
+ *   declare module 'objection' {
+ *     interface TypeConfig {
+ *       strict: true;
+ *     }
+ *   }
+ */
 export interface TypeConfig {}
 
 type IsStrict = TypeConfig extends { strict: true } ? true : false;
@@ -919,10 +910,11 @@ type CheckedColumn<M, C extends string> =
   IsConcreteModel<M> extends true ? CheckColumn<M, C> : string;
 
 /**
- * A column argument: checked against model M in strict mode, any column in
- * loose mode, where the model's properties come first, for autocompletion.
+ * A column argument: checked against model M in strict mode, the model's
+ * properties in loose mode, for autocompletion. In loose mode, other columns
+ * go through the RefArg overloads.
  */
-type ColumnArg<M, C extends string> = IfStrict<ModelProps<M & Model>, CheckedColumn<M, C>>;
+type ColumnArg<M, C extends string> = IfStrict<InsertablePropertyNames<M>, CheckedColumn<M, C>>;
 
 /**
  * The value of a column of type T in conditions: `null` is always accepted,
@@ -1071,8 +1063,8 @@ type StrictSelectionObject<M, O> = {
 /**
  * The query builder QB with its result rows narrowed to the properties P in
  * strict mode, next to the model's methods and relations, as after `select()`
- * and the aggregates, marked with SelectedBrand. Repeated selections add up. Queries
- * that aren't checked, e.g. in generic code, aren't narrowed.
+ * and the aggregates, marked with SelectedBrand. Repeated selections add up.
+ * Queries that aren't checked, e.g. in generic code, aren't narrowed.
  */
 type NarrowRows<QB extends AnyQueryBuilder, P, All extends boolean = false> = RowsQueryBuilder<
   QB,
@@ -1188,18 +1180,6 @@ export type SelectedBrand<A> = { readonly [selected]: A };
  */
 export type ExtractedBrand<A> = { readonly [extracted]: A };
 
-/**
- * The extra type of queries in strict mode: the model class C that started the
- * query, e.g. with `Person.query()`, and the modifiers P registered with
- * `modifiers()`, to check the names of modifiers, and the id I of the class,
- * for `findById()` and the other `*ById()` methods.
- */
-export interface QueryExtra<C = unknown, P = unknown, I = MaybeCompositeId> {
-  modelClass: C;
-  registered: P;
-  id: I;
-}
-
 // The results whose rows have `jsonExtract()` values, which `withGraph*()`
 // keeps instead of converting the result kind:
 type ExtractedRows =
@@ -1265,9 +1245,9 @@ type SelectedType<M, C extends string> = C extends `${infer Q}.${infer Col}`
   : ColumnType<M, C>;
 
 /**
- * The property of the column or alias C in the result rows: `snakeCaseMappers()`
- * converts them to camel case, with `upperCase: true` after lowering the case
- * of names in upper case.
+ * The property of the column or alias C in the result rows:
+ * `snakeCaseMappers()` converts them to camel case, with `upperCase: true`
+ * after lowering the case of names in upper case.
  */
 type ResultKey<M, C extends string> = M extends { ColumnNameMapping: 'snakeCase' }
   ? CamelCase<C>
@@ -1547,15 +1527,18 @@ export type JsonObjectOrFieldExpression = object | object[] | FieldExpression;
 export type Selection<QB extends AnyQueryBuilder> = ColumnRef | AnyQueryBuilder | CallbackVoid<QB>;
 
 export interface SelectMethod<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
-  <QBP extends QB>(...columns: IfStrict<ModelProps<ModelType<QBP>>, never>[]): QB;
+  // The column overload comes first, for autocompletion, and last in strict
+  // mode, so that errors are reported for it:
+  <QBP extends QB, const C extends readonly [unknown, ...unknown[]]>(
+    ...columns: IfStrict<ModelProps<ModelType<QBP>>[], StrictSelections<ModelType<QBP>, C>>
+  ): IfStrict<QB, SelectQueryBuilder<QBP, C>>;
   <QBP extends QB>(columns: IfStrict<ModelProps<ModelType<QBP>>, never>[]): QB;
 
   <QBP extends QB>(...columns: IfStrict<Selection<QBP>, never>[]): QB;
   <QBP extends QB>(columns: IfStrict<Selection<QBP>, never>[]): QB;
 
-  // Allows things like `select(1)`, not sure if we should be more specific here?
-  <QBP extends QB>(...args: IfStrict<any, never>[]): QB;
+  // Allow anything else in loose mode, like `select(1)`:
+  <QBP extends QB>(...args: IfStrict<{} | null | undefined, never>[]): QB;
 
   <QBP extends QB, const C extends readonly unknown[] = []>(
     ...columns: StrictSelections<ModelType<QBP>, C>
@@ -1584,7 +1567,7 @@ export interface JsonExtraction {
 
 // Extractions without an alias, or with several, add any properties.
 export interface JsonExtract<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never, const A extends string = string>(
     column: ColumnArg<ModelType<QBP>, C>,
     path: string,
@@ -1605,7 +1588,7 @@ export interface JsonExtract<out QB extends AnyQueryBuilder> {
 }
 
 export interface JsonSet<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     column: ColumnArg<ModelType<QBP>, C>,
     path: string,
@@ -1617,7 +1600,7 @@ export interface JsonSet<out QB extends AnyQueryBuilder> {
 }
 
 export interface JsonInsert<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     column: ColumnArg<ModelType<QBP>, C>,
     path: string,
@@ -1629,7 +1612,7 @@ export interface JsonInsert<out QB extends AnyQueryBuilder> {
 }
 
 export interface JsonRemove<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     column: ColumnArg<ModelType<QBP>, C>,
     path: string,
@@ -1640,6 +1623,17 @@ export interface JsonRemove<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereMethod<out QB extends AnyQueryBuilder> {
+  // The column overloads come first, for autocompletion:
+  <QBP extends QB, const C extends string = never, const O extends Operator = Operator>(
+    col: ColumnArg<ModelType<QBP>, C>,
+    op: O,
+    expr: OperatorValueArg<ModelType<QBP>, C, O>,
+  ): QB;
+  <QBP extends QB, const C extends string = never>(
+    col: ColumnArg<ModelType<QBP>, C>,
+    expr: ValueArg<ModelType<QBP>, C>,
+  ): QB;
+
   (condition: boolean): QB;
   (cb: CallbackVoid<QB>): QB;
   (raw: Raw): QB;
@@ -1648,7 +1642,7 @@ export interface WhereMethod<out QB extends AnyQueryBuilder> {
   (col: RefArg<QB>, op: Operator, expr: Expression<PrimitiveValue>): QB;
   (col: RefArg<QB>, expr: Expression<PrimitiveValue>): QB;
 
-  // The column overloads come last, so that errors are reported for them.
+  // The column overloads come last, so that errors are reported for them:
   <QBP extends QB, const C extends string = never, const O extends Operator = Operator>(
     col: ColumnArg<ModelType<QBP>, C>,
     op: O,
@@ -1660,14 +1654,19 @@ export interface WhereMethod<out QB extends AnyQueryBuilder> {
   ): QB;
 
   <QBP extends QB>(obj: IfStrict<PartialModelProps<ModelType<QBP>>, never>): QB;
-  // We must allow any keys in the object. The previous type
-  // is kind of useless, but maybe one day vscode and other
-  // tools can autocomplete using it.
+  // Allow any keys in loose mode. The model's properties above only serve
+  // autocompletion.
   (obj: IfStrict<object, never>): QB;
   <QBP extends QB, const O extends object = {}>(obj: O & StrictWhereObject<ModelType<QBP>, O>): QB;
 }
 
 export interface WhereLikeMethod<out QB extends AnyQueryBuilder> {
+  // The column overload comes first, for autocompletion, and last, so that
+  // errors are reported for it:
+  <QBP extends QB, const C extends string = never>(
+    col: ColumnArg<ModelType<QBP>, C>,
+    expr: Expression<string>,
+  ): QB;
   (col: RefArg<QB>, expr: Expression<string>): QB;
   <QBP extends QB, const C extends string = never>(
     col: ColumnArg<ModelType<QBP>, C>,
@@ -1688,13 +1687,12 @@ export interface WhereExistsMethod<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereInMethod<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
-  <QBP extends QB>(
-    col: IfStrict<ModelProps<ModelType<QBP>>, never>,
-    expr: Expression<PrimitiveValue>,
+  // The column overload comes first, for autocompletion, and last in strict
+  // mode, so that errors are reported for it:
+  <QBP extends QB, const C extends string = never>(
+    col: ColumnArg<ModelType<QBP>, C>,
+    expr: IfStrict<Expression<PrimitiveValue> | CallbackVoid<QB>, WhereInValues<QB, QBP, C>>,
   ): QB;
-  <QBP extends QB>(col: IfStrict<ModelProps<ModelType<QBP>>, never>, cb: CallbackVoid<QB>): QB;
-  <QBP extends QB>(col: IfStrict<ModelProps<ModelType<QBP>>, never>, qb: AnyQueryBuilder): QB;
 
   (col: RefArg<QB> | RefArg<QB>[], expr: readonly Expression<PrimitiveValue>[]): QB;
   (col: RefArg<QB> | RefArg<QB>[], cb: CallbackVoid<QB>): QB;
@@ -1702,7 +1700,7 @@ export interface WhereInMethod<out QB extends AnyQueryBuilder> {
 
   <QBP extends QB, const C extends string = never>(
     col: StrictColumn<ModelType<QBP>, C>,
-    expr: readonly ValueArg<ModelType<QBP>, C>[] | Raw | AnyQueryBuilder | CallbackVoid<QB>,
+    expr: WhereInValues<QB, QBP, C>,
   ): QB;
   <QBP extends QB, const C extends readonly unknown[] = []>(
     col: StrictColumns<ModelType<QBP>, C>,
@@ -1710,6 +1708,9 @@ export interface WhereInMethod<out QB extends AnyQueryBuilder> {
   ): QB;
 }
 
+type WhereInValues<QB extends AnyQueryBuilder, QBP extends QB, C extends string> =
+  readonly ValueArg<ModelType<QBP>, C>[] | Raw | AnyQueryBuilder | CallbackVoid<QB>;
+
 export interface WhereBetweenMethod<out QB extends AnyQueryBuilder> {
   (column: RefArg<QB>, range: [Expression<PrimitiveValue>, Expression<PrimitiveValue>]): QB;
   <QBP extends QB, const C extends string = never>(
@@ -1724,7 +1725,7 @@ export interface WhereNullMethod<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereColumnMethod<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never, const D extends string = never>(
     col1: ColumnArg<ModelType<QBP>, C>,
     op: Operator,
@@ -1747,7 +1748,7 @@ export interface WhereColumnMethod<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereJsonObject<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     col: ColumnArg<ModelType<QBP>, C>,
     value: any,
@@ -1757,7 +1758,7 @@ export interface WhereJsonObject<out QB extends AnyQueryBuilder> {
 }
 
 export interface WhereJsonPath<out QB extends AnyQueryBuilder> {
-  // These must come first so that we get autocomplete.
+  // The column overloads come first, for autocompletion:
   <QBP extends QB, const C extends string = never>(
     col: ColumnArg<ModelType<QBP>, C>,
     jsonPath: string,
@@ -2114,7 +2115,7 @@ type WriteQueryBuilder<QB extends AnyQueryBuilder, M extends Model, R> = [R] ext
  * The writes after `returning()` on single and maybe-single query builders,
  * which resolve to one row.
  */
-interface ReturningWrites<QB extends AnyQueryBuilder, M extends Model, W> {
+export interface ReturningWrites<QB extends AnyQueryBuilder, M extends Model, W> {
   update(update: PartialModelRow<M>): Rebind<QB, M, W>;
   update(): Rebind<QB, M, W>;
   patch(update: PartialModelPatch<M>): Rebind<QB, M, W>;
@@ -2239,7 +2240,8 @@ export interface GraphOptions {
   maxBatchSize?: number;
   /**
    * Apply `limit()`, `offset()` and `first()` in graph modifiers to the related
-   * items of each parent. Defaults to `true`. Only applies to `withGraphFetched()`.
+   * items of each parent. Defaults to `true`. Only applies to
+   * `withGraphFetched()`.
    */
   limitPerParent?: boolean;
 }
@@ -2706,8 +2708,6 @@ export class QueryBuilder<
   ): Promise<R | FR>;
 }
 
-export type X<T> = Promise<T>;
-
 export interface FetchGraphOptions {
   transaction?: TransactionOrKnex;
   skipFetched?: boolean;
@@ -3055,7 +3055,8 @@ export interface ConstructorFunctionType<T = any> extends PrototypeType<T> {
   new (...args: any[]): T;
 }
 
-// for internal use on generic static this deduction, copied from https://github.com/microsoft/TypeScript/issues/5863#issuecomment-1483978415
+// Used internally to infer the generic static `this`, copied from:
+// https://github.com/microsoft/TypeScript/issues/5863#issuecomment-1483978415
 export type ConstructorType<T = unknown, Static extends Record<string, any> = PrototypeType<T>> = (
   ConstructorFunctionType<T> | PrototypeType<T>
 ) & {
@@ -3132,7 +3133,7 @@ export interface ModelClass<M extends Model> extends ModelConstructor<M> {
 
   transaction<T>(callback: (trx: Transaction) => Promise<T>): Promise<T>;
   transaction<T>(
-    trxOrKnex: TransactionOrKnex,
+    trxOrKnex: TransactionOrKnex | undefined,
     callback: (trx: Transaction) => Promise<T>,
   ): Promise<T>;