objection 3.1.5 → 3.3.0

package/README.md

@@ -1,25 +1,25 @@
 [![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://stand-with-ukraine.pp.ua)
 
-[![Tests](https://github.com/Vincit/objection.js/actions/workflows/test.yml/badge.svg)](https://github.com/Vincit/objection.js)
+[![Tests](https://github.com/ditojs/objection/actions/workflows/test.yml/badge.svg)](https://github.com/ditojs/objection/actions)
 [![Join the chat at https://gitter.im/Vincit/objection.js](https://badges.gitter.im/Vincit/objection.js.svg)](https://gitter.im/Vincit/objection.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-# [Objection.js](https://vincit.github.io/objection.js)
+# [Objection.js](https://ditojs.github.io/objection/)
 
 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).
+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/ditojs/objection/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**
+- **An easy declarative way of [defining models](https://ditojs.github.io/objection/guide/models.html) and relationships between them**
+- **Simple and fun way to [fetch, insert, update and delete](https://ditojs.github.io/objection/guide/query-examples.html) objects using the full power of SQL**
+- **Powerful mechanisms for [eager loading](https://ditojs.github.io/objection/guide/query-examples.html#eager-loading), [inserting](https://ditojs.github.io/objection/guide/query-examples.html#graph-inserts) and [upserting](https://ditojs.github.io/objection/guide/query-examples.html#graph-upserts) object graphs**
+- **Easy to use [transactions](https://ditojs.github.io/objection/guide/transactions.html)**
+- **Official [TypeScript](https://github.com/ditojs/objection/blob/main/typings/objection/index.d.ts) support**
+- **Optional [JSON schema](https://ditojs.github.io/objection/guide/validation.html) validation**
+- **A way to [store complex documents](https://ditojs.github.io/objection/guide/documents.html) as single rows**
 
 What objection.js **doesn't** give you:
 
@@ -31,7 +31,7 @@ What objection.js **doesn't** give you:
 - **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.
+  written using the [raw](https://ditojs.github.io/objection/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
@@ -45,9 +45,9 @@ Check out [this issue](https://github.com/Vincit/objection.js/issues/1069) to se
 Shortcuts:
 
 - [Who uses objection.js](https://github.com/Vincit/objection.js/discussions/2464)
-- [API reference](https://vincit.github.io/objection.js/api/query-builder/)
+- [API reference](https://ditojs.github.io/objection/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)
+- [Changelog](https://ditojs.github.io/objection/release-notes/changelog.html)
+- [v1 -> v2 -> v3 migration guide](https://ditojs.github.io/objection/release-notes/migration.html)
+- [Contribution guide](https://ditojs.github.io/objection/guide/contributing.html)
+- [Plugins](https://ditojs.github.io/objection/guide/plugins.html)

package/lib/model/AjvValidator.js

@@ -5,6 +5,7 @@ const addFormats = require('ajv-formats');
 const { Validator } = require('./Validator');
 const { ValidationErrorType } = require('../model/ValidationError');
 const { isObject, once, cloneDeep: lodashCloneDeep, omit } = require('../utils/objectUtils');
+const { parseFieldExpression } = require('../utils/parseFieldExpression');
 
 class AjvValidator extends Validator {
   static init(self, conf) {
@@ -35,6 +36,9 @@ class AjvValidator extends Validator {
     // A cache for the compiled validator functions.
     self.cache = new Map();
 
+    // The cache keys of the unmodified model class schemas.
+    self.modelCacheKeys = new WeakMap();
+
     const setupAjv = (ajv) => {
       if (conf.onCreateAjv) {
         conf.onCreateAjv(ajv);
@@ -78,13 +82,24 @@ class AjvValidator extends Validator {
       json = cloneDeep(json);
     }
 
-    validator.call(model, json);
+    // Patch objects can contain field expression keys like `'meta:b'` that update
+    // a single property inside a json column. Validate them against the nested
+    // schema by converting them into nested objects like `{ meta: { b: value } }`.
+    const fieldExpressions = options.patch ? nestFieldExpressions(json) : null;
+    const validationJson = fieldExpressions ? fieldExpressions.json : json;
+
+    validator.call(model, validationJson);
     const error = parseValidationError(validator.errors, modelClass, options, this.ajvOptions);
 
     if (error) {
       throw error;
     }
 
+    if (fieldExpressions) {
+      // Copy back the changes made by Ajv options like `coerceTypes` and `removeAdditional`.
+      unnestFieldExpressions(json, fieldExpressions);
+    }
+
     return json;
   }
 
@@ -92,12 +107,23 @@ class AjvValidator extends Validator {
     // 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 cacheKey;
+
+    if (jsonSchema === modelClass.getJsonSchema()) {
+      // Optimization for the common case where jsonSchema is never modified.
+      // The key is only computed once per model class. It includes the schema
+      // contents so that model classes with the same `uniqueTag()` but
+      // different schemas don't share validators, while bound model classes
+      // with equal schemas still do.
+      cacheKey = this.modelCacheKeys.get(modelClass);
+
+      if (cacheKey === undefined) {
+        cacheKey = `${modelClass.uniqueTag()}:${createCacheKey(jsonSchema)}`;
+        this.modelCacheKeys.set(modelClass, cacheKey);
+      }
+    } else {
+      cacheKey = createCacheKey(jsonSchema);
+    }
 
     let validators = this.cache.get(cacheKey);
     let validator = null;
@@ -209,6 +235,116 @@ function parseValidationError(errors, modelClass, options, ajvOptions) {
   });
 }
 
+function nestFieldExpressions(json) {
+  const keys = Object.keys(json);
+
+  if (!keys.some(isFieldExpression)) {
+    return null;
+  }
+
+  const nested = Object.create(null);
+  const paths = new Map();
+  // The objects created here for the nested paths. Other objects are values
+  // of the input json and must not be modified.
+  const createdObjects = new Set();
+
+  for (const key of keys) {
+    if (!isFieldExpression(key)) {
+      nested[key] = json[key];
+      paths.set(key, [key]);
+    }
+  }
+
+  for (const key of keys) {
+    if (isFieldExpression(key)) {
+      const path = fieldExpressionPath(key);
+
+      // Field expressions with array access, and those that conflict with other
+      // keys of the patch, can't be validated without the current value of the
+      // json column. Leave them out of the validation.
+      if (path && setPath(nested, path, json[key], createdObjects)) {
+        paths.set(key, path);
+      }
+    }
+  }
+
+  return { json: nested, paths };
+}
+
+function unnestFieldExpressions(json, { json: nested, paths }) {
+  for (const [key, path] of paths) {
+    let value = nested;
+    let found = true;
+
+    for (const prop of path) {
+      found = isObject(value) && hasOwn(value, prop);
+
+      if (!found) {
+        break;
+      }
+
+      value = value[prop];
+    }
+
+    if (!found) {
+      // Removed by `removeAdditional`.
+      delete json[key];
+    } else if (json[key] !== value) {
+      json[key] = value;
+    }
+  }
+}
+
+function isFieldExpression(key) {
+  return key.indexOf(':') !== -1;
+}
+
+function fieldExpressionPath(key) {
+  let parsed;
+
+  try {
+    parsed = parseFieldExpression(key);
+  } catch (err) {
+    // Not a valid field expression, validate it as a top-level property.
+    return [key];
+  }
+
+  if (parsed.access.some((access) => access.type !== 'object')) {
+    return null;
+  }
+
+  return [parsed.column, ...parsed.access.map((access) => String(access.ref))];
+}
+
+function setPath(obj, path, value, createdObjects) {
+  const last = path.length - 1;
+
+  for (let i = 0; i < last; ++i) {
+    const prop = path[i];
+
+    if (!hasOwn(obj, prop)) {
+      const child = Object.create(null);
+      createdObjects.add(child);
+      obj[prop] = child;
+    } else if (!createdObjects.has(obj[prop])) {
+      return false;
+    }
+
+    obj = obj[prop];
+  }
+
+  if (hasOwn(obj, path[last])) {
+    return false;
+  }
+
+  obj[path[last]] = value;
+  return true;
+}
+
+function hasOwn(obj, prop) {
+  return Object.prototype.hasOwnProperty.call(obj, prop);
+}
+
 function cloneDeep(obj) {
   if (isObject(obj) && obj.$isObjectionModel) {
     return obj.$clone();
@@ -262,25 +398,41 @@ function objectHasDefaults(obj) {
 }
 
 function jsonSchemaWithoutRequired(jsonSchema) {
-  const subSchemaProps = ['anyOf', 'oneOf', 'allOf', 'not', 'then', 'else', 'properties'];
+  // `not` is intentionally left untouched: Stripping `required` inside it
+  // would turn it into a schema that rejects everything (e.g.
+  // `not: { required: ['a'] }` -> `not: {}`). Kept as is, it still holds for
+  // patches: Any property present in the patch is also present in the
+  // resulting object.
+  const subSchemaProps = ['anyOf', 'oneOf', 'allOf', 'then', 'else', 'properties'];
+  // `definitions` was renamed to `$defs` in draft 2019-09. Support both.
+  const definitionProps = ['definitions', '$defs'];
   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]),
-            })),
-          ),
-        }
-      : {},
+    ...definitionProps.map((prop) => definitionsWithoutRequired(jsonSchema, prop)),
     jsonSchema.discriminator && jsonSchema.discriminator.propertyName
       ? { required: [jsonSchema.discriminator.propertyName] }
       : {},
   );
 }
 
+function definitionsWithoutRequired(jsonSchema, prop) {
+  const definitions = jsonSchema && jsonSchema[prop];
+
+  if (definitions && Object.keys(definitions).length > 0) {
+    return {
+      [prop]: Object.fromEntries(
+        Object.entries(definitions).map(([key, schema]) => [
+          key,
+          jsonSchemaWithoutRequired(schema),
+        ]),
+      ),
+    };
+  } else {
+    return {};
+  }
+}
+
 function subSchemaWithoutRequired(jsonSchema, prop) {
   if (jsonSchema[prop]) {
     if (Array.isArray(jsonSchema[prop])) {
@@ -293,7 +445,10 @@ function subSchemaWithoutRequired(jsonSchema, prop) {
       } else {
         return {};
       }
-    } else if (jsonSchema.type === 'object' && prop === 'properties') {
+    } else if (prop === 'properties') {
+      // `properties` is a map of property names to schemas, regardless of the
+      // schema's `type` (which may also be e.g. `['object', 'null']`, or be
+      // missing entirely).
       return {
         [prop]: Object.fromEntries(
           Object.entries(jsonSchema[prop]).map(([key, schema]) => [

package/lib/model/Model.js

@@ -120,7 +120,7 @@ class Model {
     return json;
   }
 
-  $formatJson(json) {
+  $formatJson(json, options) {
     return json;
   }
 
@@ -721,6 +721,8 @@ Model.uidProp = '#id';
 Model.uidRefProp = '#ref';
 Model.dbRefProp = '#dbRef';
 Model.propRefRegex = /#ref{([^\.]+)\.([^}]+)}/g;
+Model.graphUnrelateProp = '#unrelate';
+Model.graphDeleteProp = '#delete';
 Model.jsonAttributes = null;
 Model.cloneObjectAttributes = true;
 Model.virtualAttributes = null;

package/lib/model/graph/ModelGraphNode.js

@@ -46,6 +46,18 @@ class ModelGraphNode {
     return this.obj[this.modelClass.dbRefProp];
   }
 
+  get toBeUnrelated() {
+    return this.obj[this.modelClass.graphUnrelateProp] === true;
+  }
+
+  get toBeDeleted() {
+    return this.obj[this.modelClass.graphDeleteProp] === true;
+  }
+
+  get toBeUnrelatedOrDeleted() {
+    return this.toBeUnrelated || this.toBeDeleted;
+  }
+
   get parentNode() {
     if (this.parentEdge) {
       return this.parentEdge.ownerNode;

package/lib/model/modelToJson.js

@@ -15,10 +15,11 @@ function toJson(model, optIn) {
     pick: null,
     omitFromJson: model.$omitFromJson() || null,
     cloneObjects: modelClass.cloneObjectAttributes,
+    format: optIn && optIn.format,
   };
 
   let json = toExternalJsonImpl(model, opt);
-  json = model.$formatJson(json);
+  json = model.$formatJson(json, opt.format);
 
   return json;
 }