4.0

.eslintrc.json

@@ -1,7 +1,8 @@
 {
   "root": true,
   "parserOptions": {
-    "ecmaVersion": "latest"
+    "ecmaVersion": "latest",
+    "sourceType": "module"
   },
   "plugins": [
     "prettier"
@@ -11,25 +12,14 @@
     "no-undef": "error"
   },
   "env": {
-    "es6": true,
-    "node": true,
-    "mocha": true
+    "es2021": true,
+    "node": true
   },
   "overrides": [
     {
-      "files": [
-        "lib/**/*.js"
-      ],
+      "files": ["tests/unit/relations/files/*.js"],
       "parserOptions": {
-        "ecmaVersion": 2020
-      }
-    },
-    {
-      "files": [
-        "tests/**/*.js"
-      ],
-      "env": {
-        "es2021": true
+        "sourceType": "script"
       }
     }
   ]

.github/workflows/docs.yml

@@ -7,7 +7,7 @@ on:
       - 'doc/**'
       - '.github/workflows/docs.yml'
       - 'package.json'
-      - 'package-lock.json'
+      - 'pnpm-lock.yaml'
   workflow_dispatch:
 
 permissions:
@@ -24,13 +24,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v7
         with:
           node-version: 22
-          cache: npm
+          cache: pnpm
       # Native modules (sqlite3) aren't needed to build the docs.
-      - run: npm ci --ignore-scripts
-      - run: npm run docs:build
+      - run: pnpm install --frozen-lockfile --ignore-scripts
+      - run: pnpm docs:build
       - uses: actions/upload-pages-artifact@v5
         with:
           path: doc/.vitepress/dist

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: tests
 
 on:
   push:
-    branches: [main]
+    branches: [next]
   pull_request:
-    branches: [main]
+    branches: [next]
 
 jobs:
   run-tests:
@@ -13,55 +13,49 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [16.x, 18.x, 20.x, 22.x, 24.x]
-        knex: [default]
+        # 20.19.0 is the oldest supported version, the first one that can
+        # require() ES modules without a flag.
+        node-version: [20.19.0, 20.x, 22.x, 24.x]
         database: [default]
-        # Also test the oldest supported knex version, MySQL 5.7 and SQL Server,
-        # each as a separate job.
+        # Also test SQL Server as a separate job.
         include:
-          - node-version: 16.x
-            knex: 2.3.0
-            database: default
           - node-version: 24.x
-            knex: default
-            database: mysql-5.7
-          - node-version: 24.x
-            knex: default
             database: mssql
 
     env:
-      COMPOSE_FILE: ${{ matrix.database == 'mysql-5.7' && 'docker-compose.yml:docker-compose.mysql57.yml' || 'docker-compose.yml' }}
-      # The MySQL 5.7 and SQL Server jobs only need their database, the default
-      # services start otherwise.
-      SERVICES: ${{ matrix.database == 'mysql-5.7' && 'mysql' || matrix.database == 'mssql' && 'mssql' || '' }}
+      # The SQL Server job only needs its database, the default services start
+      # otherwise.
+      SERVICES: ${{ matrix.database == 'mssql' && 'mssql' || '' }}
 
     steps:
       - uses: actions/checkout@v7
 
+      - uses: pnpm/action-setup@v6
+
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v7
         with:
           node-version: ${{ matrix.node-version }}
+          cache: pnpm
 
       - name: Install dependencies
-        run: npm ci
-
-      - name: Install knex ${{ matrix.knex }}
-        if: matrix.knex != 'default'
-        run: npm install --no-save knex@${{ matrix.knex }}
+        run: pnpm install --frozen-lockfile
 
       # The generated parsers have to match their grammars. One job is enough.
       - name: Check the generated parsers
-        if: matrix.node-version == '24.x' && matrix.knex == 'default' && matrix.database == 'default'
+        if: matrix.node-version == '24.x' && matrix.database == 'default'
         run: |
-          npm run build:parsers
+          pnpm build:parsers
           git diff --exit-code lib/queryBuilder/parsers
 
       # The documented minimum TypeScript version has to compile the typings
-      # and their tests. One job is enough.
-      - name: Check the typings with TypeScript 5.1
-        if: matrix.node-version == '24.x' && matrix.knex == 'default' && matrix.database == 'default'
-        run: npx --yes -p typescript@5.1.6 tsc
+      # and their tests, `pnpm test` checks them with the latest one. One job
+      # is enough.
+      - name: Check the typings with TypeScript 5.8
+        if: matrix.node-version == '24.x' && matrix.database == 'default'
+        run: |
+          pnpm dlx --package=typescript@5.8.3 tsc
+          pnpm dlx --package=typescript@5.8.3 tsc -p tests/ts/strict
 
       # Cache the database images, as their registries rate limit anonymous
       # pulls. The month in the key picks up updates of their floating tags.
@@ -104,7 +98,7 @@ jobs:
               docker save -o "$IMAGES_PATH" $IMAGES
             fi
           fi
-          npm run db:up -- $SERVICES
+          pnpm db:up $SERVICES
 
       - name: Save database images
         if: steps.cache.outcome == 'success' && steps.cache.outputs.cache-hit != 'true'
@@ -114,15 +108,13 @@ jobs:
           key: ${{ steps.images.outputs.key }}
 
       - name: Run tests
-        if: matrix.knex == 'default' && matrix.database == 'default'
-        run: npm test
+        if: matrix.database == 'default'
+        run: pnpm test
 
-      # The typings of older knex versions don't compile with current
-      # TypeScript, so only the test suite runs against them. The MySQL 5.7 and
-      # SQL Server jobs only run the tests of their database, the other jobs
+      # The SQL Server job only runs the tests of its database, the other jobs
       # already lint and check typings.
-      - name: Run tests without linting and typings
-        if: matrix.knex != 'default' || matrix.database != 'default'
+      - name: Run the tests of the database
+        if: matrix.database != 'default'
         env:
-          DATABASES: ${{ matrix.database == 'mysql-5.7' && 'mysql' || matrix.database == 'mssql' && 'mssql' || '' }}
-        run: npx mocha --slow 10 --timeout 15000 --reporter spec --recursive tests --exclude "tests/unit/relations/files/**"
+          DATABASES: ${{ matrix.database }}
+        run: pnpm vitest run

.gitignore

@@ -13,4 +13,5 @@ npm-debug.log*
 .vscode
 /**/yarn.lock
 doc/.vitepress/cache
-doc/.vitepress/dist
+doc/.vitepress/dist
+tests/bench/typings/.generated

doc/.vitepress/config.mjs

@@ -141,7 +141,7 @@ export default defineConfig({
         activeMatch: '^/release-notes/',
         items: [
           { text: 'Changelog', link: '/release-notes/changelog' },
-          { text: 'Migration to 3.0', link: '/release-notes/migration' },
+          { text: 'Migration to 4.0', link: '/release-notes/migration' },
           {
             text: 'v2.x documentation',
             link: 'https://github.com/Vincit/objection.js/tree/v2/doc',

doc/api/model/instance-methods.md

@@ -599,6 +599,8 @@ See [this section](/api/model/overview.html#model-data-lifecycle) for more infor
 | ------ | ----------------------- |
 | Object | Model as a JSON object. |
 
+In TypeScript, the JSON object is typed `ModelJson<M>`: the model's properties without methods, with the related models as `ModelJson` too. Values like dates aren't converted.
+
 ##### Examples
 
 ```js
@@ -635,9 +637,9 @@ See [this section](/api/model/overview.html#model-data-lifecycle) for more infor
 
 ```js
 class Person extends Model {
-  $parseDatabaseJson(json) {
+  $parseDatabaseJson(json, options) {
     // Remember to call the super class's implementation.
-    json = super.$parseDatabaseJson(json);
+    json = super.$parseDatabaseJson(json, options);
     // Do your conversion here.
     return json;
   }
@@ -654,11 +656,14 @@ There are a couple of requirements for the implementation:
 
 2. This function must be able to handle any subset of the model's properties coming in.You cannot assume that some column is present in the `json` object as it depends on the select statement. There can also be additional columns because of joins, aliases etc. This method must also be prepared for null values in _any_ property of the `json` object.
 
+The default implementation applies the [columnNameMappers](/api/model/static-properties.html#static-columnnamemappers) and then parses the [jsonAttributes](/api/model/static-properties.html#static-jsonattributes) as [jsonColumnFormat](/api/model/static-properties.html#static-jsoncolumnformat) says.
+
 ##### Arguments
 
 | Argument | Type   | Description                      |
 | -------- | ------ | -------------------------------- |
 | json     | Object | The JSON POJO in database format |
+| options  | Object | Optional. Passed by queries to parse the [jsonAttributes](/api/model/static-properties.html#static-jsonattributes) depending on the driver. Overrides pass it on to `super`. |
 
 ##### Return value
 
@@ -802,13 +807,14 @@ Validates the JSON before setting values.
 modelInstance.$setDatabaseJson(json);
 ```
 
-Sets the values from a JSON object in database format.
+Sets the values from a JSON object in database format, converted by [\$parseDatabaseJson](/api/model/instance-methods.html#parsedatabasejson). Called by hand, the source of `json` is unknown: unless [jsonColumnFormat](/api/model/static-properties.html#static-jsoncolumnformat) says otherwise, strings in [jsonAttributes](/api/model/static-properties.html#static-jsonattributes) that are valid JSON are parsed, and other strings are kept.
 
 ##### Arguments
 
 | Argument | Type   | Description                      |
 | -------- | ------ | -------------------------------- |
 | json     | Object | The JSON POJO in database format |
+| options  | Object | Optional. Passed by queries to parse the [jsonAttributes](/api/model/static-properties.html#static-jsonattributes) depending on the driver. Overrides pass it on to `super`. |
 
 ##### Return value
 
@@ -846,6 +852,15 @@ modelInstance.$setRelated(relation, relatedModels);
 
 Sets related models to a corresponding property in the object.
 
+The foreign keys follow the relation:
+
+- `BelongsToOneRelation`: the foreign key of the object is set to the key of the related model, e.g. `post.$setRelated('author', user)` also sets `post.authorId` to `user.id`. Clearing the relation with `null` or `[]`, or setting a related model without a key, sets the foreign key to `null`.
+- `BelongsToManyRelation`: the array of keys of the object is set to the keys of the related models, e.g. `post.$setRelated('tags', tags)` sets `post.tagIds` to the ids of `tags`, and to `[]` when the relation is cleared. Related models without a key are left out of the array.
+- `HasOneRelation` and `HasManyRelation`: the foreign keys of the related models are set to the key of the object, e.g. `user.$setRelated('posts', posts)` sets `authorId` of each post to `user.id`. The foreign keys of the models that are no longer related, because the relation is cleared or they are replaced, are set to `null`, unless they already point to another object. If the object has no key yet, the foreign keys of the related models are set to `null`.
+- `ManyToManyRelation` and `HasOneThroughRelation`: nothing is set, as the keys live in the join table.
+
+Foreign keys set on the models before are overwritten. Only `$setRelated()` and `$appendRelated()` sync the keys: [fromJson](/api/model/static-methods.html#static-fromjson), [\$setJson](/api/model/instance-methods.html#setjson), queries and direct assignments leave them as they are.
+
 ##### Arguments
 
 | Argument      | Type                                               | Description                                  |
@@ -877,7 +892,7 @@ console.log(person.children[0]);
 modelInstance.$appendRelated(relation, relatedModels);
 ```
 
-Appends related models to a corresponding property in the object.
+Appends related models to a corresponding property in the object. The foreign keys of the appended models are synced like with [\$setRelated](/api/model/instance-methods.html#setrelated), and the models already in the relation keep theirs. For `BelongsToManyRelation`, the keys of the appended models are added to the array of the object, also when the relation isn't loaded. For `BelongsToOneRelation` and `HasOneRelation`, the related model is replaced like with `$setRelated()`.
 
 ##### Arguments