@abedmurrar/objection 0.0.0-stage → 4.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Sami Koskimäki
+Copyright (c) 2026 Abed Murrar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+[![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)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @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

@@ -0,0 +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 })));
+}
+module.exports = {
+    initialize,
+};

package/lib/model/AjvValidator.js

@@ -0,0 +1,278 @@
+'use strict';
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const { Validator } = require('./Validator');
+const { ValidationErrorType } = require('../model/ValidationError');
+const { isObject, cloneDeep: cloneDeepValue, omit } = require('../utils/objectUtils');
+class AjvValidator extends Validator {
+    static init(self, conf) {
+        super.init(self, conf);
+        self.ajvOptions = Object.assign({}, conf.options, {
+            allErrors: true,
+        });
+        // Create a normal Ajv instance.
+        self.ajv = new Ajv(Object.assign({
+            useDefaults: true,
+        }, self.ajvOptions));
+        // Create an instance that doesn't set default values. We need this one
+        // to validate `patch` objects (objects that have a subset of properties).
+        self.ajvNoDefaults = new Ajv(Object.assign({}, self.ajvOptions, {
+            useDefaults: false,
+        }));
+        // Caches for the compiled validator functions: by the serialized schema,
+        // and by the schema object for the schemas of model classes.
+        self.cache = new Map();
+        self.schemaCache = new WeakMap();
+        const setupAjv = (ajv) => {
+            if (conf.onCreateAjv) {
+                conf.onCreateAjv(ajv);
+            }
+            // Only add Ajv formats if they weren't added in user-space already
+            if (!ajv.formats['date-time']) {
+                addFormats(ajv);
+            }
+        };
+        setupAjv(self.ajv);
+        setupAjv(self.ajvNoDefaults);
+    }
+    beforeValidate({ json, model, options, ctx }) {
+        ctx.jsonSchema = model.constructor.getJsonSchema();
+        // Objection model's have a `$beforeValidate` hook that is allowed to modify the schema.
+        // We need to clone the schema in case the function modifies it. We only do this in the
+        // rare case that the given model has implemented the hook.
+        if (model.$beforeValidate !== model.$objectionModelClass.prototype.$beforeValidate) {
+            ctx.jsonSchema = cloneDeep(ctx.jsonSchema);
+            const ret = model.$beforeValidate(ctx.jsonSchema, json, options);
+            if (ret !== undefined) {
+                ctx.jsonSchema = ret;
+            }
+        }
+    }
+    validate({ json, model, options, ctx }) {
+        if (!ctx.jsonSchema) {
+            return json;
+        }
+        const modelClass = model.constructor;
+        const validator = this.getValidator(modelClass, ctx.jsonSchema, !!options.patch);
+        // We need to clone the input json if we are about to set default values.
+        if (!options.mutable && !options.patch && setsDefaultValues(ctx.jsonSchema)) {
+            json = cloneDeep(json);
+        }
+        validator.call(model, json);
+        const error = parseValidationError(validator.errors, modelClass, options, this.ajvOptions);
+        if (error) {
+            throw error;
+        }
+        return json;
+    }
+    getValidator(modelClass, jsonSchema, isPatchObject) {
+        // Use the Ajv custom serializer if provided.
+        const createCacheKey = this.ajvOptions.serialize || JSON.stringify;
+        // The compiled validators are cached by the serialized schema. In the
+        // common case where jsonSchema is the model class's own schema, they are
+        // also cached by the schema object, so the costly createCacheKey function
+        // runs once per schema object. Classes bound to a knex instance share their
+        // validator with the class they are bound from, and a bound class can have
+        // a schema of its own, so the cache isn't keyed by the class name.
+        const isClassSchema = jsonSchema === modelClass.getJsonSchema() && isObject(jsonSchema);
+        let validators = isClassSchema ? this.schemaCache.get(jsonSchema) : undefined;
+        let validator = null;
+        if (!validators) {
+            const cacheKey = createCacheKey(jsonSchema);
+            validators = this.cache.get(cacheKey);
+            if (!validators) {
+                validators = {
+                    // Validator created for the schema object without `required` properties
+                    // using the Ajv instance that doesn't set default values.
+                    patchValidator: null,
+                    // Validator created for the unmodified schema.
+                    normalValidator: null,
+                };
+                this.cache.set(cacheKey, validators);
+            }
+            if (isClassSchema) {
+                this.schemaCache.set(jsonSchema, validators);
+            }
+        }
+        if (isPatchObject) {
+            validator = validators.patchValidator;
+            if (!validator) {
+                validator = this.compilePatchValidator(jsonSchema);
+                validators.patchValidator = validator;
+            }
+        }
+        else {
+            validator = validators.normalValidator;
+            if (!validator) {
+                validator = this.compileNormalValidator(jsonSchema);
+                validators.normalValidator = validator;
+            }
+        }
+        return validator;
+    }
+    compilePatchValidator(jsonSchema) {
+        jsonSchema = jsonSchemaWithoutRequired(jsonSchema);
+        // We need to use the ajv instance that doesn't set the default values.
+        return this.ajvNoDefaults.compile(jsonSchema);
+    }
+    compileNormalValidator(jsonSchema) {
+        return this.ajv.compile(jsonSchema);
+    }
+}
+function parseValidationError(errors, modelClass, options, ajvOptions) {
+    if (!errors) {
+        return null;
+    }
+    const relationNames = modelClass.getRelationNames();
+    const errorHash = {};
+    let numErrors = 0;
+    for (const error of errors) {
+        // If additionalProperties = false, relations can pop up as additionalProperty
+        // errors. Skip those.
+        if (error.params &&
+            error.params.additionalProperty &&
+            relationNames.includes(error.params.additionalProperty)) {
+            continue;
+        }
+        let path = error.instancePath.replace(/\//g, '.');
+        if (error.params) {
+            if (error.params.missingProperty) {
+                path += `.${error.params.missingProperty}`;
+            }
+            else if (error.params.additionalProperty) {
+                path += `.${error.params.additionalProperty}`;
+            }
+        }
+        const key = `${options.dataPath || ''}${path}`.substring(1);
+        // More than one error can occur for the same key in Ajv, merge them in the array:
+        const array = errorHash[key] || (errorHash[key] = []);
+        // Prepare error object
+        const errorObj = {
+            message: error.message,
+            keyword: error.keyword,
+            params: error.params,
+        };
+        // Add data if verbose enabled
+        if (ajvOptions.verbose) {
+            errorObj.data = error.data;
+        }
+        // Use unshift instead of push so that the last error ends up at [0],
+        // preserving previous behavior where only the last error was stored.
+        array.unshift(errorObj);
+        ++numErrors;
+    }
+    if (numErrors === 0) {
+        return null;
+    }
+    return modelClass.createValidationError({
+        type: ValidationErrorType.ModelValidation,
+        data: errorHash,
+    });
+}
+function cloneDeep(obj) {
+    if (isObject(obj) && obj.$isObjectionModel) {
+        return obj.$clone();
+    }
+    else {
+        return cloneDeepValue(obj);
+    }
+}
+// Whether a schema has default values is checked for every validated model,
+// so the answer is cached per schema object.
+const setsDefaultValuesCache = new WeakMap();
+function setsDefaultValues(jsonSchema) {
+    if (!isObject(jsonSchema)) {
+        return jsonSchema && jsonSchema.properties && hasDefaults(jsonSchema.properties);
+    }
+    let result = setsDefaultValuesCache.get(jsonSchema);
+    if (result === undefined) {
+        result = !!(jsonSchema.properties && hasDefaults(jsonSchema.properties));
+        setsDefaultValuesCache.set(jsonSchema, result);
+    }
+    return result;
+}
+function hasDefaults(obj) {
+    if (Array.isArray(obj)) {
+        return arrayHasDefaults(obj);
+    }
+    else {
+        return objectHasDefaults(obj);
+    }
+}
+function arrayHasDefaults(arr) {
+    for (let i = 0, l = arr.length; i < l; ++i) {
+        const val = arr[i];
+        if (isObject(val) && hasDefaults(val)) {
+            return true;
+        }
+    }
+    return false;
+}
+function objectHasDefaults(obj) {
+    const keys = Object.keys(obj);
+    for (let i = 0, l = keys.length; i < l; ++i) {
+        const key = keys[i];
+        if (key === 'default') {
+            return true;
+        }
+        else {
+            const val = obj[key];
+            if (isObject(val) && hasDefaults(val)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function jsonSchemaWithoutRequired(jsonSchema) {
+    const subSchemaProps = ['anyOf', 'oneOf', 'allOf', 'not', 'then', 'else', 'properties'];
+    return Object.assign(omit(jsonSchema, ['required', ...subSchemaProps]), ...subSchemaProps.map((prop) => subSchemaWithoutRequired(jsonSchema, prop)), jsonSchema && jsonSchema.definitions && Object.keys(jsonSchema.definitions).length > 0
+        ? {
+            definitions: Object.assign(...Object.keys(jsonSchema.definitions).map((prop) => ({
+                [prop]: jsonSchemaWithoutRequired(jsonSchema.definitions[prop]),
+            }))),
+        }
+        : {}, jsonSchema.discriminator && jsonSchema.discriminator.propertyName
+        ? { required: [jsonSchema.discriminator.propertyName] }
+        : {});
+}
+function subSchemaWithoutRequired(jsonSchema, prop) {
+    if (jsonSchema[prop]) {
+        if (Array.isArray(jsonSchema[prop])) {
+            const schemaArray = jsonSchemaArrayWithoutRequired(jsonSchema[prop]);
+            if (schemaArray.length !== 0) {
+                return {
+                    [prop]: schemaArray,
+                };
+            }
+            else {
+                return {};
+            }
+        }
+        else if (jsonSchema.type === 'object' && prop === 'properties') {
+            return {
+                [prop]: Object.fromEntries(Object.entries(jsonSchema[prop]).map(([key, schema]) => [
+                    key,
+                    jsonSchemaWithoutRequired(schema),
+                ])),
+            };
+        }
+        else {
+            return {
+                [prop]: jsonSchemaWithoutRequired(jsonSchema[prop]),
+            };
+        }
+    }
+    else {
+        return {};
+    }
+}
+function jsonSchemaArrayWithoutRequired(jsonSchemaArray) {
+    return jsonSchemaArray.map(jsonSchemaWithoutRequired).filter(isNotEmptyObject);
+}
+function isNotEmptyObject(obj) {
+    return Object.keys(obj).length !== 0;
+}
+module.exports = {
+    AjvValidator,
+};