Merge branch 'upstream-master'

Author: falkenhawk

.github/workflows/test.yml

@@ -2,17 +2,17 @@ name: tests
 
 on:
   push:
-    branches: [master]
+    branches: [main]
   pull_request:
-    branches: [master]
+    branches: [main]
 
 jobs:
   run-tests:
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x, 16.x, 18.x, 20.x]
+        node-version: [14.x, 16.x, 18.x, 20.x, 22.x]
 
     steps:
       - uses: actions/checkout@v2
@@ -26,7 +26,7 @@ jobs:
         run: npm ci
 
       - name: Run docker compose
-        run: docker-compose up -d
+        run: docker compose up -d
 
       - name: Setup test db
         run: node setup-test-db.js

README.md

@@ -17,7 +17,7 @@ What objection.js gives you:
 - **Simple and fun way to [fetch, insert, update and delete](https://vincit.github.io/objection.js/guide/query-examples.html) objects using the full power of SQL**
 - **Powerful mechanisms for [eager loading](https://vincit.github.io/objection.js/guide/query-examples.html#eager-loading), [inserting](https://vincit.github.io/objection.js/guide/query-examples.html#graph-inserts) and [upserting](https://vincit.github.io/objection.js/guide/query-examples.html#graph-upserts) object graphs**
 - **Easy to use [transactions](https://vincit.github.io/objection.js/guide/transactions.html)**
-- **Official [TypeScript](https://github.com/Vincit/objection.js/blob/master/typings/objection/index.d.ts) support**
+- **Official [TypeScript](https://github.com/Vincit/objection.js/blob/main/typings/objection/index.d.ts) support**
 - **Optional [JSON schema](https://vincit.github.io/objection.js/guide/validation.html) validation**
 - **A way to [store complex documents](https://vincit.github.io/objection.js/guide/documents.html) as single rows**
 
@@ -36,18 +36,18 @@ What objection.js **doesn't** give you:
   For simple things it is useful that the database schema is automatically generated from the model definitions,
   but usually just gets in your way when doing anything non-trivial. Objection.js leaves the schema related things
   to you. knex has a great [migration tool](https://knexjs.org/guide/migrations.html) that we recommend for this job. Check
-  out the [example project](https://github.com/Vincit/objection.js/tree/master/examples/koa-ts).
+  out the [example project](https://github.com/Vincit/objection.js/tree/main/examples/koa-ts).
 
-The best way to get started is to clone our [example project](https://github.com/Vincit/objection.js/tree/master/examples/koa) and start playing with it. There's also a [typescript version](https://github.com/Vincit/objection.js/tree/master/examples/koa-ts) available.
+The best way to get started is to clone our [example project](https://github.com/Vincit/objection.js/tree/main/examples/koa) and start playing with it. There's also a [typescript version](https://github.com/Vincit/objection.js/tree/main/examples/koa-ts) available.
 
 Check out [this issue](https://github.com/Vincit/objection.js/issues/1069) to see who is using objection and what they think about it.
 
 Shortcuts:
 
-- [Who uses objection.js](https://github.com/Vincit/objection.js/issues/1069)
+- [Who uses objection.js](https://github.com/Vincit/objection.js/discussions/2464)
 - [API reference](https://vincit.github.io/objection.js/api/query-builder/)
-- [Example projects](https://github.com/Vincit/objection.js/tree/master/examples)
+- [Example projects](https://github.com/Vincit/objection.js/tree/main/examples)
 - [Changelog](https://vincit.github.io/objection.js/release-notes/changelog.html)
-- [v1 -> v2 migration guide](https://vincit.github.io/objection.js/release-notes/migration.html)
+- [v1 -> v2 -> v3 migration guide](https://vincit.github.io/objection.js/release-notes/migration.html)
 - [Contribution guide](https://vincit.github.io/objection.js/guide/contributing.html)
 - [Plugins](https://vincit.github.io/objection.js/guide/plugins.html)

doc/.vuepress/theme/index.js

@@ -10,7 +10,7 @@ module.exports = (_, ctx) => ({
     const isAlgoliaSearch =
       themeConfig.algolia ||
       Object.keys((siteConfig.locales && themeConfig.locales) || {}).some(
-        (base) => themeConfig.locales[base].algolia
+        (base) => themeConfig.locales[base].algolia,
       );
 
     return {

doc/README.md

@@ -19,7 +19,7 @@ What objection.js gives you:
 - **Simple and fun way to [fetch, insert, update and delete](/guide/query-examples.html) objects using the full power of SQL**
 - **Powerful mechanisms for [eager loading](/guide/query-examples.html#eager-loading), [inserting](/guide/query-examples.html#graph-inserts) and [upserting](/guide/query-examples.html#graph-upserts) object graphs**
 - **Easy to use [transactions](/guide/transactions.html)**
-- **Official [TypeScript](https://github.com/Vincit/objection.js/blob/master/typings/objection/index.d.ts) support**
+- **Official [TypeScript](https://github.com/Vincit/objection.js/blob/main/typings/objection/index.d.ts) support**
 - **Optional [JSON schema](/guide/validation.html) validation**
 - **A way to [store complex documents](/guide/documents.html) as single rows**
 
@@ -33,8 +33,8 @@ What objection.js **doesn't** give you:
   For simple things it is useful that the database schema is automatically generated from the model definitions,
   but usually just gets in your way when doing anything non-trivial. Objection.js leaves the schema related things
   to you. knex has a great [migration tool](https://knexjs.org/guide/migrations.html) that we recommend for this job. Check
-  out the [example project](https://github.com/Vincit/objection.js/tree/master/examples/koa-ts).
+  out the [example project](https://github.com/Vincit/objection.js/tree/main/examples/koa-ts).
 
-The best way to get started is to clone our [example project](https://github.com/Vincit/objection.js/tree/master/examples/koa) and start playing with it. There's also a [typescript version](https://github.com/Vincit/objection.js/tree/master/examples/koa-ts) available.
+The best way to get started is to clone our [example project](https://github.com/Vincit/objection.js/tree/main/examples/koa) and start playing with it. There's also a [typescript version](https://github.com/Vincit/objection.js/tree/main/examples/koa-ts) available.
 
 Check out [this issue](https://github.com/Vincit/objection.js/issues/1069) to see who is using objection and what they think about it.

doc/api/model/instance-methods.md

@@ -1036,19 +1036,19 @@ called explicitly when needed.
 | ---------------------------------------------------- | -------------------- |
 | [ValidationError](/api/types/#class-validationerror) | If validation fails. |
 
-## $omit()
+## $omitFromJson()
 
 ```js
-modelInstance.$omit(keys);
+modelInstance.$omitFromJson(props);
 ```
 
-Omits a set of properties.
+Omits a set of properties when converting the model to JSON.
 
 ##### Arguments
 
-| Argument | Type                                                     | Description  |
-| -------- | -------------------------------------------------------- | ------------ |
-| keys     | string<br>string[]<br>Object&lt;string,&nbsp;boolean&gt; | keys to omit |
+| Argument | Type                                                     | Description   |
+| -------- | -------------------------------------------------------- | ------------- |
+| props    | string<br>string[]<br>Object&lt;string,&nbsp;boolean&gt; | props to omit |
 
 ##### Return value
 
@@ -1058,48 +1058,46 @@ Omits a set of properties.
 
 ##### Examples
 
-Omits a set of properties.
-
 ```js
 const json = person
   .fromJson({ firstName: 'Jennifer', lastName: 'Lawrence', age: 24 })
-  .$omit('lastName')
-  .toJSON();
+  .$omitFromJson('lastName')
+  .$toJson();
 
 console.log(_.has(json, 'lastName')); // --> false
 ```
 
 ```js
 const json = person
   .fromJson({ firstName: 'Jennifer', lastName: 'Lawrence', age: 24 })
-  .$omit(['lastName'])
-  .toJSON();
+  .$omitFromJson(['lastName'])
+  .$toJson();
 
 console.log(_.has(json, 'lastName')); // --> false
 ```
 
 ```js
 const json = person
   .fromJson({ firstName: 'Jennifer', lastName: 'Lawrence', age: 24 })
-  .$omit({ lastName: true })
-  .toJSON();
+  .$omitFromJson({ lastName: true })
+  .$toJson();
 
 console.log(_.has(json, 'lastName')); // --> false
 ```
 
-## $pick()
+## $omitFromDatabaseJson()
 
 ```js
-modelInstance.$pick(keys);
+modelInstance.$omitFromDatabaseJson(props);
 ```
 
-Picks a set of properties.
+Omits a set of properties when converting the model to database JSON.
 
 ##### Arguments
 
-| Argument | Type                                                     | Description  |
-| -------- | -------------------------------------------------------- | ------------ |
-| keys     | string<br>string[]<br>Object&lt;string,&nbsp;boolean&gt; | keys to pick |
+| Argument | Type                                                     | Description   |
+| -------- | -------------------------------------------------------- | ------------- |
+| props    | string<br>string[]<br>Object&lt;string,&nbsp;boolean&gt; | props to omit |
 
 ##### Return value
 
@@ -1112,26 +1110,26 @@ Picks a set of properties.
 ```js
 const json = person
   .fromJson({ firstName: 'Jennifer', lastName: 'Lawrence', age: 24 })
-  .$pick('firstName', 'age')
-  .toJSON();
+  .$omitFromDatabaseJson('lastName')
+  .$toDatabaseJson();
 
 console.log(_.has(json, 'lastName')); // --> false
 ```
 
 ```js
 const json = person
   .fromJson({ firstName: 'Jennifer', lastName: 'Lawrence', age: 24 })
-  .$pick(['firstName', 'age'])
-  .toJSON();
+  .$omitFromJson(['lastName'])
+  .$toDatabaseJson();
 
 console.log(_.has(json, 'lastName')); // --> false
 ```
 
 ```js
 const json = person
   .fromJson({ firstName: 'Jennifer', lastName: 'Lawrence', age: 24 })
-  .$pick({ firstName: true, age: true })
-  .toJSON();
+  .$omitFromJson({ lastName: true })
+  .$toDatabaseJson();
 
 console.log(_.has(json, 'lastName')); // --> false
 ```

doc/api/model/static-properties.md

@@ -118,6 +118,8 @@ Composite id can be specified by giving an array of column names.
 
 Defaults to 'id'.
 
+You can return `null` in order to tell objection there is no primary key. This may be useful in models of join tables.
+
 ## `static` jsonSchema
 
 ```js

doc/guide/contributing.md

@@ -13,7 +13,7 @@ When creating an issue there are couple of things you need to remember:
    Answer the following questions: Which objection version are you using? What are you doing? What code are you running? What is happening? What are you expecting to happen instead? If you provide code examples (please do!), **use the actual code you are running**. People often leave out details or use made up examples because they think they are only leaving out irrelevant stuff. If you do that, you have already made an assumption about what the problem is and it's usually something else. Also provide all possible stack traces and error messages.
 
 3. **If possible, provide an actual reproduction**
-   The fastest way to get your bug fixed or problem solved is to create a simple standalone app or a test case that demonstrates your problem. There's a file called [reproduction-template.js](https://github.com/Vincit/objection.js/blob/master/reproduction-template.js) you can use as a starting point for your reproduction.
+   The fastest way to get your bug fixed or problem solved is to create a simple standalone app or a test case that demonstrates your problem. There's a file called [reproduction-template.js](https://github.com/Vincit/objection.js/blob/main/reproduction-template.js) you can use as a starting point for your reproduction.
 
 Please bear in mind that objection has thousands of tests and if you run into a problem, say with `insert` method, it doesn't mean that `insert` is completely broken, but some small part of it you are using is. That's why enough context is necessary. It's not enough to say, "insert fails". You need to provide the code that fails and usually the models that are used too. And let's say this again: **don't provide made up code examples!** When you do, you only write the parts you think are relevant and usually leave out the useful information. Use the actual code that you have tested to fail.
 
@@ -41,7 +41,7 @@ git clone [email protected]:<your-account>/objection.js.git objection
 
 3. **Run `npm install` at the root of the repo**
 
-4. **Run `docker-compose up` at the root of the repo**
+4. **Run `docker compose up` at the root of the repo**
    - If you have local databases running, shut them down or port binding will conflict.
 
 5. **Create test users and databases by running `node setup-test-db` at the root of the repo**
@@ -53,7 +53,7 @@ git clone [email protected]:<your-account>/objection.js.git objection
 You can run the tests on a subset of databases by setting the `DATABASES` env variable
 
 ```bash
-# Only run tests on sqlite. No need for docker-compose.
+# Only run tests on sqlite. No need for docker compose.
 DATABASES=sqlite3 npm test
 ```
 

doc/guide/getting-started.md

@@ -4,7 +4,7 @@ To use objection.js all you need to do is [initialize knex](https://knexjs.org/g
 
 The next step is to create some migrations and models and start using objection.js. The best way to get started is to check out one of our example projects:
 
-- [The minimal example](https://github.com/Vincit/objection.js/tree/master/examples/minimal) contains the bare minimum for you to start testing out things with objection.
+- [The minimal example](https://github.com/Vincit/objection.js/tree/main/examples/minimal) contains the bare minimum for you to start testing out things with objection.
 
 ```bash
 git clone [email protected]:Vincit/objection.js.git objection
@@ -13,7 +13,7 @@ npm install
 npm start
 ```
 
-- [The koa example project](https://github.com/Vincit/objection.js/tree/master/examples/koa) is a simple [koa](https://koajs.com) server. The `client.js` file contains a bunch of http requests for you to start playing with the REST API.
+- [The koa example project](https://github.com/Vincit/objection.js/tree/main/examples/koa) is a simple [koa](https://koajs.com) server. The `client.js` file contains a bunch of http requests for you to start playing with the REST API.
 
 ```bash
 git clone [email protected]:Vincit/objection.js.git objection
@@ -22,7 +22,7 @@ npm install
 npm start
 ```
 
-We also have a [typescript version](https://github.com/Vincit/objection.js/tree/master/examples/koa-ts) of the example.
+We also have a [typescript version](https://github.com/Vincit/objection.js/tree/main/examples/koa-ts) of the example.
 
 Also check out our [API reference](/api/query-builder/) and [recipe book](/recipes/raw-queries.html).
 

doc/guide/plugins.md

@@ -16,10 +16,11 @@ A curated list of plugins and modules for objection. Only plugins that follow [t
 
 - [objection-filter](https://github.com/tandg-digital/objection-filter) - API filtering on data and related models
 - [objection-graphql](https://github.com/vincit/objection-graphql) - Automatically generates rich graphql schema for objection models
+- [objectionjs-graphql](https://www.npmjs.com/package/objectionjs-graphql) - Automatically generates GraphQl schema for objection models compatible with Objection 3.x (Graph fetch support)
 
 ## Plugin development best practices
 
-When possible, objection.js plugins should be implemented as [class mixins](http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/). A mixin is simply a function that takes a class as an argument and returns a subclass. Plugins should not modify [objection.Model](/api/model/), [objection.QueryBuilder](/api/query-builder/) or any other global variables directly. See the [example plugin](https://github.com/Vincit/objection.js/tree/master/examples/plugin) for more info. There is also [another example](https://github.com/Vincit/objection.js/tree/master/examples/plugin-with-options) that should be followed if your plugin takes options or configuration parameters.
+When possible, objection.js plugins should be implemented as [class mixins](http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/). A mixin is simply a function that takes a class as an argument and returns a subclass. Plugins should not modify [objection.Model](/api/model/), [objection.QueryBuilder](/api/query-builder/) or any other global variables directly. See the [example plugin](https://github.com/Vincit/objection.js/tree/main/examples/plugin) for more info. There is also [another example](https://github.com/Vincit/objection.js/tree/main/examples/plugin-with-options) that should be followed if your plugin takes options or configuration parameters.
 
 Mixin is just a function that takes a class and returns an extended subclass.
 

doc/guide/relations.md

@@ -134,11 +134,36 @@ class Person extends Model {
 }
 ```
 
-## Require loops
+## Require loops (non ECMAScript modules only)
 
 Require loops (circular dependencies, circular requires) are a very common problem when defining relations. Whenever a module `A` imports module `B` that immediately (synchronously) imports module `A`, you create a require loop that node.js or objection cannot solve automatically. A require loop usually leads to the other imported value to be an empty object which causes all kinds of problems. Objection attempts to detect these situations and mention the words `require loop` in the thrown error. Objection offers multiple solutions to this problem. See the circular dependency solutions examples in this section. In addition to objection's solutions, you can always organize your code so that such loops are not created.
 
-Solutions to require loops
+If you are using [ECMAScript modules](https://nodejs.org/api/esm.html), circular imports are not a problem. You can just do:
+
+```js
+import Animal from "./Animal.js";
+
+class Person extends Model {
+  static get tableName() {
+    return "persons";
+  }
+
+  static get relationMappings() {
+    return {
+      pets: {
+        relation: Model.HasManyRelation,
+        modelClass: Animal,
+        join: {
+          from: "persons.id",
+          to: "animals.ownerId",
+        },
+      },
+    };
+  }
+}
+```
+
+However if you are not using ECMAScript modules, solutions to require loops are:
 
 ```js
 class Person extends Model {
@@ -208,3 +233,4 @@ class Person extends Model {
   }
 }
 ```
+