@abedmurrar/objection 4.0.0-alpha.0 → 4.0.0-beta.1

package/README.md

@@ -1,70 +1,106 @@
 [![Tests](https://github.com/abedmurrar/objection.js/actions/workflows/test.yml/badge.svg)](https://github.com/abedmurrar/objection.js/actions/workflows/test.yml)
 [![npm](https://img.shields.io/npm/v/@abedmurrar/objection/next)](https://www.npmjs.com/package/@abedmurrar/objection)
 
-> **`@abedmurrar/objection`** is a fork of [objection.js](https://github.com/Vincit/objection.js) 3.1.5. It adds:
->
-> - **Strict TypeScript types.** Query results contain exactly the relations that were loaded, relation expressions and modifier names are checked, and `Model.ref()` only accepts real columns.
-> - **MySQL support** for JSON field expressions and the `whereJson*` methods, `fn.*` helpers for every MySQL 8.4 function, and batch inserts.
-> - **Expressions without raw SQL**, like `Pet.ref('age').gte(3)` and `fn.count().filter(...)`, plus window functions.
-> - **Fixes** for JSON key escaping (SQL injection), `orWhere` escaping relation conditions, and `for()`.
->
-> See the [changelog](doc/release-notes/changelog.md) and the [migration guide](doc/release-notes/migration.md).
->
-> ```sh
-> npm install @abedmurrar/objection@next knex
-> ```
->
-> To keep `import { Model } from 'objection'` working in existing code, install it under the name `objection`:
->
-> ```sh
-> npm install objection@npm:@abedmurrar/objection@next
-> ```
-
-# [Objection.js](https://vincit.github.io/objection.js)
-
-Objection.js is an [ORM](https://en.wikipedia.org/wiki/Object-relational_mapping) for [Node.js](https://nodejs.org/) that aims to stay out of your way and make it as easy as possible to use the full power of SQL and the underlying database engine while still making the common stuff easy and enjoyable.
-
-Even though ORM is the best commonly known acronym to describe objection, a more accurate description is to call it **a relational query builder**. You get all the benefits of an SQL query builder but also a powerful set of tools for working with relations.
-
-Objection.js is built on an SQL query builder called [knex](http://knexjs.org). All databases supported by knex are supported by objection.js. **SQLite3**, **Postgres** and **MySQL** are [thoroughly tested](https://github.com/Vincit/objection.js/actions).
-
-What objection.js gives you:
-
-- **An easy declarative way of [defining models](https://vincit.github.io/objection.js/guide/models.html) and relationships between them**
-- **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/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**
-
-What objection.js **doesn't** give you:
-
-- **A fully object oriented view of your database**
-  With objection you don't work with entities. You work with queries. Objection doesn't try to wrap every concept with an 
-  object oriented equivalent. The best attempt to do that (IMO) is Hibernate, which is excellent, but it has 800k lines
-  of code and a lot more concepts to learn than SQL itself. The point is, writing a good traditional ORM is borderline
-  impossible. Objection attempts to provide a completely different way of working with SQL.
-- **A custom query DSL. SQL is used as a query language.**
-  This doesn't mean you have to write SQL strings though. A query builder based on [knex](http://knexjs.org) is
-  used to build the SQL. However, if the query builder fails you for some reason, raw SQL strings can be easily
-  written using the [raw](https://vincit.github.io/objection.js/api/objection/#raw) helper function.
-- **Automatic database schema creation and migration from model definitions.**
-  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/main/examples/koa-ts).
-
-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/discussions/2464)
-- [API reference](https://vincit.github.io/objection.js/api/query-builder/)
-- [Example projects](https://github.com/Vincit/objection.js/tree/main/examples)
-- [Changelog](https://vincit.github.io/objection.js/release-notes/changelog.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)
+# @abedmurrar/objection
+
+**A fast, strictly typed SQL ORM for Node.js, built on [knex](https://knexjs.org).** Define your models and relations once, then query them with the full power of SQL: eager loading, graph inserts and upserts, transactions, JSON columns and expressions, with types that know what each query returns.
+
+It started as a fork of [objection.js](https://github.com/Vincit/objection.js) 3.1.5 and keeps its API, so objection.js code runs on it apart from the [breaking changes](doc/fork/breaking-changes.md), most of which fix queries that read or changed the wrong rows.
+
+```sh
+npm install @abedmurrar/objection@next knex
+```
+
+## Why this one
+
+- **Types that know what you loaded.** Relations are inferred from `relationMappings`, query results only contain the relations the query fetched, and relation expressions, modifier names and `Model.ref()` columns are checked at compile time. See [TypeScript](doc/fork/typescript.md).
+- **Fast.** objection's own work for a query takes 13% to 19% less time than in objection.js 3.1.5, `toJSON()` 44% less, validation 55% less, and a validated insert in a new transaction 91% less, with the same SQL and results. See [Performance](doc/fork/performance.md).
+- **MySQL and MariaDB as first-class databases**, not only postgres: JSON field expressions, the `whereJson*` methods, batch inserts and an `fn.*` helper for every MySQL 8.4 function. MariaDB 10.6 and 11.4 are tested in CI. See [MySQL and MariaDB](doc/fork/mysql.md).
+- **Expressions without raw SQL**, like `Pet.ref('age').gte(3)`, `fn.count().filter(...)`, `fn.case()` and window functions. See [Expressions](doc/fork/expressions.md).
+- **Safer.** JSON field keys are escaped (in objection.js 3.1.5 they allowed SQL injection), an `orWhere()` can no longer match the rows of other relation owners, and `for()` is no longer silently ignored. See [Breaking changes](doc/fork/breaking-changes.md).
+- **Modern.** Node.js 24+, ES modules and CommonJS from one package, knex 3.3, the knex methods objection didn't have, TypeScript 7, no lodash and no bluebird, and `npm audit` reports nothing. The source is moving to TypeScript.
+
+## A quick look
+
+```ts
+import { Model, defineRelations } from '@abedmurrar/objection';
+import { knex } from 'knex';
+
+Model.knex(knex({ client: 'pg', connection: process.env.DATABASE_URL }));
+
+class Pet extends Model {
+  static tableName = 'pets';
+
+  id!: number;
+  name!: string;
+  ownerId!: number;
+}
+
+class Person extends Model {
+  static tableName = 'persons';
+
+  id!: number;
+  firstName!: string;
+
+  static relationMappings = defineRelations(() => ({
+    pets: {
+      relation: Model.HasManyRelation,
+      modelClass: Pet,
+      join: { from: 'persons.id', to: 'pets.ownerId' },
+    },
+  }));
+}
+
+const people = await Person.query().where('firstName', 'like', 'J%').withGraphFetched('pets');
+
+people[0].pets[0].name; // `pets` is in the type because the query loaded it
+people[0].firstName;
+
+// A person and their pets in one insert.
+await Person.query().insertGraph({
+  firstName: 'Jennifer',
+  pets: [{ name: 'Doggo' }],
+});
+```
+
+## Requirements
+
+| Dependency | Version                                                |
+| ---------- | ------------------------------------------------------ |
+| Node.js    | 24 or newer (24 and 26 are tested)                     |
+| knex       | 3.3 or newer                                           |
+| MySQL      | 8.0.17 or newer (tested on 8.4 with `mysql2`)          |
+| MariaDB    | 10.6 or newer (tested on 10.6 and 11.4 with `mariadb`) |
+| SQLite     | 3.35 or newer for batch inserts                        |
+
+Postgres is tested on the current release.
+
+## Coming from objection.js
+
+Install the package under the name `objection`, and existing `import { Model } from 'objection'` code keeps working:
+
+```sh
+npm install objection@npm:@abedmurrar/objection@next
+```
+
+Then read the [breaking changes](doc/fork/breaking-changes.md) and the [migration guide](doc/release-notes/migration.md). Most changes make queries do what they look like they do. The stricter types can flag code that only compiled because the old types were loose; the [TypeScript page](doc/fork/typescript.md) lists an opt-out for every check.
+
+## Documentation
+
+- [What this package adds](doc/fork/README.md) to objection.js, page by page.
+- **[The documentation site](https://abedmurrar.github.io/objection.js/)**: the guide and the API reference for everything else (models, relations, queries, eager loading, graphs, transactions and validation), which come from objection.js.
+- [Changelog](doc/release-notes/changelog.md) and [migration guide](doc/release-notes/migration.md).
+- [Contributing](doc/guide/contributing.md) and [releasing](RELEASING.md).
+
+## The approach
+
+Like objection.js, this is less a classic ORM than **a relational query builder**: you work with queries, not with an object graph that hides the SQL.
+
+- You get a declarative way to define models and their relations, the full power of SQL to fetch and change rows, eager loading, graph inserts and upserts, transactions, optional JSON schema validation, and a way to store documents in JSON columns.
+- You don't get a query language of its own (the query builder is knex, and `raw()` is there for anything it can't express), or a schema generated from the models: [knex migrations](https://knexjs.org/guide/migrations.html) do that job.
+
+## Credits
+
+This project is built on [objection.js](https://github.com/Vincit/objection.js) by [Sami Koskimäki](https://github.com/koskimas) and its many contributors, maintained at [Vincit](https://github.com/Vincit). Its design, its API, most of its code and much of the documentation come from there. Thank you.
+
+Released under the [MIT license](LICENSE), like objection.js.

package/lib/index.mjs

@@ -0,0 +1,6 @@
+// The ES module entry of the package. It re-exports the CommonJS build, so
+// `import { Model }` and `require(...).Model` are the same class and there is
+// only one copy of objection in memory (no dual package hazard).
+import objection from './objection.js';
+export const { Model, QueryBuilder, QueryBuilderBase, QueryBuilderOperation, RelationExpression, ValidationError, NotFoundError, AjvValidator, Validator, Relation, HasOneRelation, HasManyRelation, BelongsToOneRelation, HasOneThroughRelation, ManyToManyRelation, transaction, initialize, compose, mixin, defineRelations, ref, val, raw, fn, snakeCaseMappers, knexSnakeCaseMappers, knexIdentifierMapping, DBError, UniqueViolationError, NotNullViolationError, ForeignKeyViolationError, ConstraintViolationError, CheckViolationError, DataError, } = objection;
+export default objection;

package/lib/initialize.js

@@ -1,14 +1,11 @@
 'use strict';
-
 async function initialize(knex, modelClasses) {
-  if (!modelClasses) {
-    modelClasses = knex;
-    knex = modelClasses[0].knex();
-  }
-
-  await Promise.all(modelClasses.map((modelClass) => modelClass.fetchTableMetadata({ knex })));
+    if (!modelClasses) {
+        modelClasses = knex;
+        knex = modelClasses[0].knex();
+    }
+    await Promise.all(modelClasses.map((modelClass) => modelClass.fetchTableMetadata({ knex })));
 }
-
 module.exports = {
-  initialize,
+    initialize,
 };