@abedmurrar/objection 0.0.0-stage → 4.0.0-alpha.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,70 @@
-# 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`** 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)

package/lib/.eslintrc.json

@@ -0,0 +1,8 @@
+{
+  "parserOptions": {
+    "sourceType": "script"
+  },
+  "rules": {
+    "strict": "error"
+  }
+}

package/lib/initialize.js

@@ -0,0 +1,14 @@
+'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,325 @@
+'use strict';
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const { Validator } = require('./Validator');
+const { ValidationErrorType } = require('../model/ValidationError');
+const { isObject, once, cloneDeep: lodashCloneDeep, 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,
+      }),
+    );
+
+    // A cache for the compiled validator functions.
+    self.cache = new Map();
+
+    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;
+
+    // Optimization for the common case where jsonSchema is never modified.
+    // In that case we don't need to call the costly createCacheKey function.
+    const cacheKey =
+      jsonSchema === modelClass.getJsonSchema()
+        ? modelClass.uniqueTag()
+        : createCacheKey(jsonSchema);
+
+    let validators = this.cache.get(cacheKey);
+    let validator = null;
+
+    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 (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;
+  }
+
+  let relationNames = modelClass.getRelationNames();
+  let 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 lodashCloneDeep(obj);
+  }
+}
+
+function setsDefaultValues(jsonSchema) {
+  return jsonSchema && jsonSchema.properties && hasDefaults(jsonSchema.properties);
+}
+
+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,
+};