objection 3.4.1 → 3.5.0

package/lib/queryBuilder/graph/insert/GraphInsertAction.js

@@ -208,7 +208,11 @@ class GraphInsertAction extends GraphAction {
     return Promise.all(
       nodes.map((node) => {
         if (node.parentEdge) {
-          return node.parentEdge.relation.beforeInsert(node.obj, parentBuilder.context());
+          return node.parentEdge.relation.beforeInsert(
+            node.obj,
+            parentBuilder.context(),
+            node.parentNode.obj,
+          );
         } else {
           return null;
         }

package/lib/queryBuilder/operations/InsertGraphOperation.js

@@ -63,7 +63,12 @@ class InsertGraphOperation extends DelegateOperation {
     if (this.relation) {
       // We still need to call the relation before insert hook if the the
       // delegate operation is a RelationInsertOperation.
-      return this.relation.executeBeforeInsert(this.models, builder.context(), result);
+      return this.relation.executeBeforeInsert(
+        this.models,
+        builder.context(),
+        result,
+        this.delegate.ownerModel,
+      );
     } else {
       return result;
     }

package/lib/relations/Relation.js

@@ -219,8 +219,12 @@ class Relation {
     });
   }
 
-  executeBeforeInsert(models, queryContext, result) {
-    return mapAfterAllReturn(models, (model) => this.beforeInsert(model, queryContext), result);
+  executeBeforeInsert(models, queryContext, result, owner) {
+    return mapAfterAllReturn(
+      models,
+      (model) => this.beforeInsert(model, queryContext, owner),
+      result,
+    );
   }
 
   createError(message) {

package/lib/relations/RelationInsertOperation.js

@@ -11,9 +11,21 @@ class RelationInsertOperation extends InsertOperation {
     this.assignResultToOwner = true;
   }
 
+  get ownerModel() {
+    // The owner model passed to the relation's `beforeInsert` hook. Only known
+    // if the query was started from a single model instance.
+    const { owner } = this;
+    return owner && owner.isModels && owner.modelArray.length === 1 ? owner.model : undefined;
+  }
+
   async onBefore2(builder, result) {
     const queryContext = builder.context();
-    result = await this.relation.executeBeforeInsert(this.models, queryContext, result);
+    result = await this.relation.executeBeforeInsert(
+      this.models,
+      queryContext,
+      result,
+      this.ownerModel,
+    );
     return super.onBefore2(builder, result);
   }
 

package/lib/utils/identifierMapping.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { isObject } = require('./objectUtils');
+const { isObject, isPlainObject } = require('./objectUtils');
 
 // Super fast memoize for single argument functions.
 function memoize(func) {
@@ -149,8 +149,9 @@ function mapLastPart(mapper, separator) {
 }
 
 // Returns a function that takes an object as an input and maps the object's keys
-// using `mapper`. If the input is not an object, the input is returned unchanged.
-function keyMapper(mapper) {
+// using `mapper`, and its values using the optional `valueMapper`. If the input
+// is not an object, the input is returned unchanged.
+function keyMapper(mapper, valueMapper) {
   return (obj) => {
     if (!isObject(obj) || Array.isArray(obj)) {
       return obj;
@@ -161,7 +162,7 @@ function keyMapper(mapper) {
 
     for (let i = 0, l = keys.length; i < l; ++i) {
       const key = keys[i];
-      out[mapper(key)] = obj[key];
+      out[mapper(key)] = valueMapper ? valueMapper(obj[key]) : obj[key];
     }
 
     return out;
@@ -189,10 +190,16 @@ function snakeCaseMappers(opt = {}) {
   };
 }
 
-function knexIdentifierMappers({ parse, format, idSeparator = ':' } = {}) {
+function knexIdentifierMappers({ parse, format, idSeparator = ':', mapNestedKeys = false } = {}) {
   const formatId = memoize(mapLastPart(format, idSeparator));
   const parseId = memoize(mapLastPart(parse, idSeparator));
   const parseKeys = keyMapper(parseId);
+  // With `mapNestedKeys`, also map the keys of plain objects one level down, as
+  // in the rows knex returns with its `nestTables: true` option on MySQL:
+  // `{ tableName: { columnName: value } }`.
+  const parseRow = mapNestedKeys
+    ? keyMapper(parseId, (value) => (isPlainObject(value) ? parseKeys(value) : value))
+    : parseKeys;
 
   return {
     wrapIdentifier(identifier, origWrap) {
@@ -204,12 +211,12 @@ function knexIdentifierMappers({ parse, format, idSeparator = ':' } = {}) {
         const output = new Array(result.length);
 
         for (let i = 0, l = result.length; i < l; ++i) {
-          output[i] = parseKeys(result[i]);
+          output[i] = parseRow(result[i]);
         }
 
         return output;
       } else {
-        return parseKeys(result);
+        return parseRow(result);
       }
     },
   };
@@ -219,10 +226,11 @@ function knexSnakeCaseMappers(opt = {}) {
   return knexIdentifierMappers({
     parse: (str) => camelCase(str, opt),
     format: (str) => snakeCase(str, opt),
+    mapNestedKeys: opt.mapNestedKeys,
   });
 }
 
-function knexIdentifierMapping(colToProp) {
+function knexIdentifierMapping(colToProp, { mapNestedKeys } = {}) {
   const propToCol = Object.keys(colToProp).reduce((propToCol, column) => {
     propToCol[colToProp[column]] = column;
     return propToCol;
@@ -231,6 +239,7 @@ function knexIdentifierMapping(colToProp) {
   return knexIdentifierMappers({
     parse: (column) => colToProp[column] || column,
     format: (prop) => propToCol[prop] || prop,
+    mapNestedKeys,
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objection",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "An SQL-friendly ORM for Node.js",
   "main": "lib/objection.js",
   "license": "MIT",

package/typings/objection/index.d.ts

@@ -19,6 +19,11 @@ import { Knex } from 'knex';
 // Export the entire Objection namespace.
 export = Objection;
 
+// Phantom brand of the relation types, used by `TypedRelationMappings`.
+declare const relationKind: unique symbol;
+// Phantom brand of `Generated` properties.
+declare const generated: unique symbol;
+
 declare namespace Objection {
   const raw: RawFunction;
   const val: ValueFunction;
@@ -462,6 +467,65 @@ declare namespace Objection {
           : Expression<F>
         : Expression<F>;
 
+  /**
+   * Marks a model property whose value the database generates, like an
+   * auto-incremented id, a timestamp or a column with a default value. It
+   * reads as T and accepts T, but `Insertable` and `InsertableGraph` treat
+   * the property as optional:
+   *
+   *   id!: Generated<number>;
+   */
+  export type Generated<T> = T extends null | undefined ? T : T & GeneratedBrand;
+
+  interface GeneratedBrand {
+    readonly [generated]?: true;
+  }
+
+  /**
+   * Insert keys are optional for optional, nullable and generated properties.
+   */
+  type OptionalInsertPropertyNames<M> = {
+    [K in keyof M]-?: {} extends Pick<M, K>
+      ? K
+      : null extends M[K]
+        ? K
+        : typeof generated extends keyof NonNullable<M[K]>
+          ? K
+          : never;
+  }[keyof M];
+
+  type InsertablePropertyNames<M> = Exclude<DataPropertyNames<M>, RelationPropertyNames<M>>;
+
+  /**
+   * The data to insert a model M with `insert()`. Unlike `PartialModelObject`,
+   * all properties are required except optional, nullable and `Generated`
+   * ones. Relation properties are left out.
+   */
+  export type Insertable<M extends Model> = {
+    [K in Exclude<InsertablePropertyNames<M>, OptionalInsertPropertyNames<M>>]: Expression<M[K]>;
+  } & {
+    [K in Extract<InsertablePropertyNames<M>, OptionalInsertPropertyNames<M>>]?: Expression<M[K]>;
+  };
+
+  /**
+   * Like `Insertable`, but for `insertGraph()`: relation properties are
+   * optional and hold the insertable graphs of the related models, or
+   * references to existing ones through `#dbRef` or `#ref`.
+   */
+  export type InsertableGraph<M extends Model> = Insertable<M> &
+    Omit<GraphParameters, '#dbRef' | '#ref'> & {
+      [K in RelationPropertyNames<M>]?: InsertableGraphField<M[K]>;
+    };
+
+  type InsertableGraphReference = { '#dbRef': MaybeCompositeId } | { '#ref': string };
+
+  type InsertableGraphField<F> =
+    NonNullable<F> extends (infer I extends Model)[]
+      ? (InsertableGraph<I> | InsertableGraphReference)[]
+      : NonNullable<F> extends infer I extends Model
+        ? InsertableGraph<I> | InsertableGraphReference | Extract<F, null>
+        : never;
+
   /**
    * Extracts the property names (excluding relations) of a model class.
    */
@@ -1488,6 +1552,11 @@ declare namespace Objection {
     model: M,
     context: QueryContext,
   ) => Promise<void> | void;
+  type RelationMappingBeforeInsertHook<M extends Model> = (
+    model: M,
+    context: QueryContext,
+    owner?: Model,
+  ) => Promise<void> | void;
   type StringOrReferenceBuilder = string | ReferenceBuilder;
   type RelationMappingColumnRef = StringOrReferenceBuilder | StringOrReferenceBuilder[];
 
@@ -1497,7 +1566,7 @@ declare namespace Objection {
     join: RelationJoin;
     modify?: Modifier<QueryBuilderType<M>>;
     filter?: Modifier<QueryBuilderType<M>>;
-    beforeInsert?: RelationMappingHook<M>;
+    beforeInsert?: RelationMappingBeforeInsertHook<M>;
   }
 
   export interface RelationJoin {
@@ -1518,6 +1587,67 @@ declare namespace Objection {
 
   export interface RelationType extends Constructor<Relation> {}
 
+  // The relation types are branded so that `TypedRelationMappings` can tell
+  // them apart. The brand is optional, so any `RelationType` is assignable.
+  export interface BelongsToOneRelationType extends RelationType {
+    readonly [relationKind]?: 'BelongsToOne';
+  }
+  export interface HasOneRelationType extends RelationType {
+    readonly [relationKind]?: 'HasOne';
+  }
+  export interface HasManyRelationType extends RelationType {
+    readonly [relationKind]?: 'HasMany';
+  }
+  export interface ManyToManyRelationType extends RelationType {
+    readonly [relationKind]?: 'ManyToMany';
+  }
+  export interface HasOneThroughRelationType extends RelationType {
+    readonly [relationKind]?: 'HasOneThrough';
+  }
+
+  /**
+   * Names of the properties of M that hold related models.
+   */
+  type RelationPropertyNames<M> = {
+    [K in keyof M]-?: NonNullable<M[K]> extends Model | Model[] ? K : never;
+  }[keyof M];
+
+  type TypedModelClassSpecifier<M extends Model> =
+    string | ModelConstructor<M> | (() => ModelConstructor<M>);
+
+  /**
+   * A `RelationMapping` for related models of type M with relation type R.
+   */
+  export interface TypedRelationMapping<
+    M extends Model,
+    R extends RelationType = RelationType,
+  > extends RelationMapping<M> {
+    relation: R;
+    modelClass: TypedModelClassSpecifier<M>;
+  }
+
+  type TypedRelationMappingFor<T> =
+    NonNullable<T> extends (infer I extends Model)[]
+      ? TypedRelationMapping<I, HasManyRelationType | ManyToManyRelationType>
+      : NonNullable<T> extends infer I extends Model
+        ? TypedRelationMapping<
+            I,
+            BelongsToOneRelationType | HasOneRelationType | HasOneThroughRelationType
+          >
+        : never;
+
+  /**
+   * Relation mappings checked against the relation properties of model M.
+   * Use it with `satisfies`, so the inferred type of the mappings is kept:
+   *
+   *   static relationMappings = {
+   *     pets: { ... },
+   *   } satisfies TypedRelationMappings<Person>;
+   */
+  export type TypedRelationMappings<M extends Model> = [RelationPropertyNames<M>] extends [never]
+    ? Record<string, never>
+    : { [K in RelationPropertyNames<M>]?: TypedRelationMappingFor<M[K]> };
+
   export interface Relation {
     name: string;
     ownerModelClass: typeof Model;
@@ -1528,6 +1658,7 @@ declare namespace Objection {
     joinTable: string;
     joinTableOwnerProp: RelationProperty;
     joinTableRelatedProp: RelationProperty;
+    isOneToOne(): boolean;
   }
 
   export interface RelationProperty {
@@ -1598,6 +1729,22 @@ declare namespace Objection {
      * Only used by `snakeCaseMappers`.
      */
     preserveJsonKeys?: boolean;
+    /**
+     * Also convert the keys of plain objects one level down in the results,
+     * e.g. the rows of knex's `nestTables: true` option on MySQL. Also applies
+     * to JSON columns parsed by the driver.
+     * Only used by `knexSnakeCaseMappers`.
+     */
+    mapNestedKeys?: boolean;
+  }
+
+  export interface KnexIdentifierMappingOptions {
+    /**
+     * Also convert the keys of plain objects one level down in the results,
+     * e.g. the rows of knex's `nestTables: true` option on MySQL. Also applies
+     * to JSON columns parsed by the driver.
+     */
+    mapNestedKeys?: boolean;
   }
 
   export interface ColumnNameMappers {
@@ -1619,7 +1766,7 @@ declare namespace Objection {
   }
 
   export interface KnexIdentifierMappingFactory {
-    (colToProp: Record<string, string>): KnexMappers;
+    (colToProp: Record<string, string>, options?: KnexIdentifierMappingOptions): KnexMappers;
   }
 
   export type ValidationErrorType =
@@ -1732,11 +1879,11 @@ declare namespace Objection {
     ref: ReferenceFunction;
     fn: FunctionFunction;
 
-    BelongsToOneRelation: RelationType;
-    HasOneRelation: RelationType;
-    HasManyRelation: RelationType;
-    ManyToManyRelation: RelationType;
-    HasOneThroughRelation: RelationType;
+    BelongsToOneRelation: BelongsToOneRelationType;
+    HasOneRelation: HasOneRelationType;
+    HasManyRelation: HasManyRelationType;
+    ManyToManyRelation: ManyToManyRelationType;
+    HasOneThroughRelation: HasOneThroughRelationType;
 
     defaultGraphOptions?: GraphOptions;
 
@@ -1843,11 +1990,11 @@ declare namespace Objection {
     static ref: ReferenceFunction;
     static fn: FunctionFunction;
 
-    static BelongsToOneRelation: RelationType;
-    static HasOneRelation: RelationType;
-    static HasManyRelation: RelationType;
-    static ManyToManyRelation: RelationType;
-    static HasOneThroughRelation: RelationType;
+    static BelongsToOneRelation: BelongsToOneRelationType;
+    static HasOneRelation: HasOneRelationType;
+    static HasManyRelation: HasManyRelationType;
+    static ManyToManyRelation: ManyToManyRelationType;
+    static HasOneThroughRelation: HasOneThroughRelationType;
 
     static defaultGraphOptions?: GraphOptions;