objection 3.1.4 → 3.2.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "objection",
-  "version": "3.1.4",
+  "version": "3.2.0",
   "description": "An SQL-friendly ORM for Node.js",
   "main": "lib/objection.js",
   "license": "MIT",
   "scripts": {
     "test": "npm run eslint && mocha --slow 10 --timeout 15000 --reporter spec --recursive tests --exclude \"tests/unit/relations/files/**\" && npm run test:typings",
     "test:fast": "mocha --slow 10 --timeout 15000 --reporter spec --recursive tests --bail --exclude \"tests/unit/relations/files/**\"",
-    "test:typings": "tsc",
+    "test:typings": "tsc && prettier --check \"typings/**/*.ts\" \"tests/ts/**/*.ts\"",
     "prettier": "prettier --write \"{examples,lib,tests,testUtils,typings,doc}/**/*.{js,ts}\"",
     "eslint": "eslint --format codeframe \"examples/**/*.js\" \"lib/**/*.js\" \"tests/**/*.js\"",
     "docs:dev": "vuepress dev doc",
@@ -30,8 +30,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git://github.com/vincit/objection.js.git"
+    "url": "git+https://github.com/ditojs/objection.git"
   },
+  "bugs": {
+    "url": "https://github.com/ditojs/objection/issues"
+  },
+  "homepage": "https://github.com/ditojs/objection",
   "engines": {
     "node": ">=14.0.0"
   },
@@ -53,28 +57,28 @@
   ],
   "types": "./typings/objection/index.d.ts",
   "dependencies": {
-    "ajv": "^8.12.0",
-    "ajv-formats": "^2.1.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "db-errors": "^0.2.3"
   },
   "peerDependencies": {
     "knex": ">=1.0.1"
   },
   "devDependencies": {
-    "@types/node": "^20.10.0",
+    "@types/node": "^22.15.3",
     "chai": "^4.3.10",
     "chai-subset": "^1.6.0",
     "eslint": "^8.54.0",
     "eslint-formatter-codeframe": "^7.32.1",
-    "eslint-plugin-prettier": "^5.0.1",
+    "eslint-plugin-prettier": "^5.3.1",
     "expect.js": "^0.3.1",
-    "knex": "^3.0.1",
-    "mocha": "^10.2.0",
+    "knex": "^3.1.0",
+    "mocha": "^11.2.2",
     "mysql": "^2.18.1",
-    "pg": "^8.11.3",
-    "prettier": "3.2.5",
-    "sqlite3": "^5.1.6",
-    "typescript": ">=5.3.2",
+    "pg": "^8.15.6",
+    "prettier": "3.9.9",
+    "sqlite3": "^5.1.7",
+    "typescript": ">=5.8.3",
     "vuepress": "1.9.10"
   }
 }

package/typings/objection/index.d.ts

@@ -30,6 +30,7 @@ declare namespace Objection {
 
   const snakeCaseMappers: SnakeCaseMappersFactory;
   const knexSnakeCaseMappers: KnexSnakeCaseMappersFactory;
+  const knexIdentifierMapping: KnexIdentifierMappingFactory;
 
   const transaction: transaction;
   const initialize: initialize;
@@ -126,11 +127,13 @@ declare namespace Objection {
     | string
     | number
     | boolean
+    | bigint
     | Date
     | Buffer
     | string[]
     | number[]
     | boolean[]
+    | bigint[]
     | Date[]
     | Buffer[]
     | null;
@@ -158,10 +161,7 @@ declare namespace Objection {
   type AnyModelConstructor = ModelConstructor<Model>;
   type ModifierFunction<QB extends AnyQueryBuilder> = (qb: QB, ...args: any[]) => void;
   type Modifier<QB extends AnyQueryBuilder = AnyQueryBuilder> =
-    | ModifierFunction<QB>
-    | string
-    | string[]
-    | Record<string, Expression<PrimitiveValue>>;
+    ModifierFunction<QB> | string | string[] | Record<string, Expression<PrimitiveValue>>;
   type OrderByDirection = 'asc' | 'desc' | 'ASC' | 'DESC';
   type OrderByNulls = 'first' | 'last';
 
@@ -201,10 +201,10 @@ declare namespace Objection {
    */
   type PartialModelObject<T extends Model> = {
     [K in DataPropertyNames<T>]?: Defined<T[K]> extends Model
-      ? T[K]
+      ? T[K] | PartialModelObject<Defined<T[K]>>
       : Defined<T[K]> extends Array<infer I>
         ? I extends Model
-          ? I[]
+          ? I[] | PartialModelObject<I>[]
           : Expression<T[K]>
         : Expression<T[K]>;
   };
@@ -216,6 +216,8 @@ declare namespace Objection {
     '#dbRef'?: MaybeCompositeId;
     '#ref'?: string;
     '#id'?: string;
+    '#unrelate'?: boolean;
+    '#delete'?: boolean;
   };
 
   /**
@@ -597,6 +599,7 @@ declare namespace Objection {
 
   interface WithMethod<QB extends AnyQueryBuilder> {
     (alias: string, expr: CallbackVoid<QB> | AnyQueryBuilder | Raw): QB;
+    (alias: string, columns: string[], expr: CallbackVoid<QB> | AnyQueryBuilder | Raw): QB;
   }
 
   interface JoinRelatedOptions {
@@ -612,6 +615,7 @@ declare namespace Objection {
     (table: TableRef<QB>, leftCol: ColumnRef, op: Operator, rightCol: ColumnRef): QB;
     (table: TableRef<QB>, leftCol: ColumnRef, rightCol: ColumnRef): QB;
     (table: TableRef<QB>, cb: CallbackVoid<Knex.JoinClause>): QB;
+    (table: TableRef<QB>, columns: { [leftCol: string]: ColumnRef }): QB;
     (table: TableRef<QB>, raw: Raw): QB;
     (raw: Raw): QB;
   }
@@ -624,6 +628,7 @@ declare namespace Objection {
 
   interface AggregateMethod<QB extends AnyQueryBuilder> {
     (column: ColumnRef): QB;
+    (aliasToColumnDict: { [alias: string]: ColumnRef }): QB;
   }
 
   interface CountMethod<QB extends AnyQueryBuilder> {
@@ -655,7 +660,7 @@ declare namespace Objection {
   interface FirstMethod {
     <QB extends AnyQueryBuilder>(
       this: QB,
-    ): QB extends ArrayQueryBuilder<QB> ? MaybeSingleQueryBuilder<QB> : QB;
+    ): [ResultType<QB>] extends [any[]] ? MaybeSingleQueryBuilder<QB> : QB;
   }
 
   type ForIdValue = MaybeCompositeId | AnyQueryBuilder;
@@ -693,10 +698,11 @@ declare namespace Objection {
   }
 
   interface TableRefForMethod {
-    (modelClass: ModelClass<Model> | typeof Model): string;
+    (modelClassOrTableName: string | AnyModelConstructor): string;
   }
 
   interface AliasForMethod<QB extends AnyQueryBuilder> {
+    (modelClassOrTableName: string | AnyModelConstructor): string | null;
     (modelClassOrTableName: string | AnyModelConstructor, alias: string): QB;
   }
 
@@ -707,7 +713,7 @@ declare namespace Objection {
   interface ReturningMethod {
     <QB extends AnyQueryBuilder>(
       this: QB,
-      column: string | Raw | (string | Raw)[],
+      column: string | Raw | (string | Raw)[] | readonly (string | Raw)[],
     ): QB extends NumberQueryBuilder<QB> ? ArrayQueryBuilder<QB> : QB;
   }
 
@@ -856,6 +862,8 @@ declare namespace Objection {
   export class QueryBuilder<M extends Model, R = M[]> implements CatchablePromiseLike<R> {
     static forClass: ForClassMethod;
 
+    constructor(modelClass: ModelConstructor<M>);
+
     select: SelectMethod<this>;
     columns: SelectMethod<this>;
     column: SelectMethod<this>;
@@ -1031,6 +1039,7 @@ declare namespace Objection {
     increment: IncrementDecrementMethod<this>;
     decrement: IncrementDecrementMethod<this>;
     first: FirstMethod;
+    none: IdentityMethod<this>;
 
     orderBy: OrderByMethod<this>;
     orderByRaw: OrderByRawMethod<this>;
@@ -1070,7 +1079,7 @@ declare namespace Objection {
     insert(insert: PartialModelObject<M>[]): ArrayQueryBuilder<this>;
     insert(): SingleQueryBuilder<this>;
 
-    onConflict(column?: string | string[] | true): this;
+    onConflict(column?: ColumnRef | ColumnRef[] | true): this;
     ignore(): this;
     merge(merge?: PartialModelObject<M> | string[]): this;
 
@@ -1091,9 +1100,7 @@ declare namespace Objection {
     truncate(): Promise<void>;
     allowGraph: AllowGraphMethod<this>;
 
-    throwIfNotFound: (
-      arg?: any,
-    ) => R extends Model | undefined ? SingleQueryBuilder<QueryBuilder<M, M>> : this;
+    throwIfNotFound: (arg?: any) => R extends Model | undefined ? SingleQueryBuilder<this> : this;
 
     returning: ReturningMethod;
     forUpdate: IdentityMethod<this>;
@@ -1110,6 +1117,8 @@ declare namespace Objection {
     modelClass: ModelClassMethod<M>;
     tableNameFor: TableRefForMethod;
     tableRefFor: TableRefForMethod;
+    tableName(): string;
+    tableRef(): string;
     reject: OneArgMethod<any, this>;
     resolve: OneArgMethod<any, this>;
     transacting: OneArgMethod<TransactionOrKnex, this>;
@@ -1120,12 +1129,13 @@ declare namespace Objection {
     toKnexQuery<T extends {} = ModelObject<M>>(): Knex.QueryBuilder<T, T[]>;
     knex(knex?: Knex): Knex;
     clone(): this;
+    emptyInstance(): this;
 
     page(page: number, pageSize: number): PageQueryBuilder<this>;
     range(): PageQueryBuilder<this>;
     range(start: number, end: number): PageQueryBuilder<this>;
-    offset(offset: number): this;
-    limit(limit: number): this;
+    offset(offset: number, options?: boolean | { skipBinding?: boolean }): this;
+    limit(limit: number, options?: boolean | { skipBinding?: boolean }): this;
     resultSize(): Promise<number>;
 
     runBefore: RunBeforeMethod<this>;
@@ -1302,6 +1312,7 @@ declare namespace Objection {
 
   export interface ToJsonOptions extends CloneOptions {
     virtuals?: boolean | string[];
+    format?: Pojo;
   }
 
   export interface ValidatorContext {
@@ -1334,6 +1345,7 @@ declare namespace Objection {
     upperCase?: boolean;
     underscoreBeforeDigits?: boolean;
     underscoreBetweenUppercaseLetters?: boolean;
+    noDoubleUnderscores?: boolean;
   }
 
   export interface ColumnNameMappers {
@@ -1354,11 +1366,12 @@ declare namespace Objection {
     (options?: SnakeCaseMappersOptions): KnexMappers;
   }
 
+  export interface KnexIdentifierMappingFactory {
+    (colToProp: Record<string, string>): KnexMappers;
+  }
+
   export type ValidationErrorType =
-    | 'ModelValidation'
-    | 'RelationExpression'
-    | 'UnallowedRelation'
-    | 'InvalidGraph';
+    'ModelValidation' | 'RelationExpression' | 'UnallowedRelation' | 'InvalidGraph';
 
   export class ValidationError extends Error {
     constructor(args: CreateValidationErrorArgs & { modelClass?: ModelClass<Model> });
@@ -1423,22 +1436,39 @@ declare namespace Objection {
     new (): T;
   }
 
+  interface PrototypeType<T> extends Function {
+    prototype: T;
+  }
+
+  interface ConstructorFunctionType<T = any> extends PrototypeType<T> {
+    new (...args: any[]): T;
+  }
+
+  // for internal use on generic static this deduction, copied from https://github.com/microsoft/TypeScript/issues/5863#issuecomment-1483978415
+  type ConstructorType<T = unknown, Static extends Record<string, any> = PrototypeType<T>> = (
+    ConstructorFunctionType<T> | PrototypeType<T>
+  ) & {
+    [Key in keyof Static]: Static[Key];
+  };
+
   export interface ModelConstructor<M extends Model> extends Constructor<M> {}
 
   export interface ModelClass<M extends Model> extends ModelConstructor<M> {
     QueryBuilder: typeof QueryBuilder;
 
     tableName: string;
-    idColumn: string | string[];
+    idColumn: null | string | string[] | readonly string[];
     jsonSchema: JSONSchema;
     relationMappings: RelationMappings | RelationMappingsThunk;
     modelPaths: string[];
-    jsonAttributes: string[];
+    jsonAttributes: string[] | readonly string[];
     virtualAttributes: string[];
     uidProp: string;
     uidRefProp: string;
     dbRefProp: string;
     propRefRegex: RegExp;
+    graphUnrelateProp: string;
+    graphDeleteProp: string;
     pickJsonSchemaProperties: boolean;
     relatedFindQueryMutates: boolean;
     relatedInsertQueryMutates: boolean;
@@ -1473,6 +1503,9 @@ declare namespace Objection {
     fromJson(json: object, opt?: ModelOptions): M;
     fromDatabaseJson(json: object): M;
 
+    columnNameToPropertyName(columnName: string): string;
+    propertyNameToColumnName(propertyName: string): string;
+
     createValidator(): Validator;
     createValidationError(args: CreateValidationErrorArgs): Error;
     createNotFoundError(queryContext: QueryContext, args: CreateNotFoundErrorArgs): Error;
@@ -1535,16 +1568,18 @@ declare namespace Objection {
     static QueryBuilder: typeof QueryBuilder;
 
     static tableName: string;
-    static idColumn: string | string[];
+    static idColumn: null | string | string[] | readonly string[];
     static jsonSchema: JSONSchema;
     static relationMappings: RelationMappings | RelationMappingsThunk;
     static modelPaths: string[];
-    static jsonAttributes: string[];
+    static jsonAttributes: string[] | readonly string[];
     static virtualAttributes: string[];
     static uidProp: string;
     static uidRefProp: string;
     static dbRefProp: string;
     static propRefRegex: RegExp;
+    static graphUnrelateProp: string;
+    static graphDeleteProp: string;
     static pickJsonSchemaProperties: boolean;
     static relatedFindQueryMutates: boolean;
     static relatedInsertQueryMutates: boolean;
@@ -1565,12 +1600,12 @@ declare namespace Objection {
     static defaultGraphOptions?: GraphOptions;
 
     static query<M extends Model>(
-      this: Constructor<M>,
+      this: ConstructorType<M>,
       trxOrKnex?: TransactionOrKnex,
     ): QueryBuilderType<M>;
 
     static relatedQuery<M extends Model, K extends keyof M>(
-      this: Constructor<M>,
+      this: ConstructorType<M>,
       relationName: K,
       trxOrKnex?: TransactionOrKnex,
     ): ArrayRelatedQueryBuilder<M[K]>;
@@ -1580,8 +1615,11 @@ declare namespace Objection {
       trxOrKnex?: TransactionOrKnex,
     ): QueryBuilderType<RM>;
 
-    static fromJson<M extends Model>(this: Constructor<M>, json: object, opt?: ModelOptions): M;
-    static fromDatabaseJson<M extends Model>(this: Constructor<M>, json: object): M;
+    static fromJson<M extends Model>(this: ConstructorType<M>, json: object, opt?: ModelOptions): M;
+    static fromDatabaseJson<M extends Model>(this: ConstructorType<M>, json: object): M;
+
+    static columnNameToPropertyName(columnName: string): string;
+    static propertyNameToColumnName(propertyName: string): string;
 
     static createValidator(): Validator;
     static createValidationError(args: CreateValidationErrorArgs): Error;
@@ -1596,7 +1634,7 @@ declare namespace Objection {
 
     static transaction<T>(callback: (trx: Transaction) => Promise<T>): Promise<T>;
     static transaction<T>(
-      trxOrKnex: TransactionOrKnex,
+      trxOrKnex: TransactionOrKnex | undefined,
       callback: (trx: Transaction) => Promise<T>,
     ): Promise<T>;
 
@@ -1604,14 +1642,14 @@ declare namespace Objection {
     static bindTransaction<M>(this: M, trxOrKnex: TransactionOrKnex): M;
 
     static fetchGraph<M extends Model>(
-      this: Constructor<M>,
+      this: ConstructorType<M>,
       modelOrObject: PartialModelObject<M>,
       expression: RelationExpression<M>,
       options?: FetchGraphOptions,
     ): SingleQueryBuilder<QueryBuilderType<M>>;
 
     static fetchGraph<M extends Model>(
-      this: Constructor<M>,
+      this: ConstructorType<M>,
       modelOrObject: PartialModelObject<M>[],
       expression: RelationExpression<M>,
       options?: FetchGraphOptions,
@@ -1667,7 +1705,7 @@ declare namespace Objection {
     $formatDatabaseJson(json: Pojo): Pojo;
     $parseDatabaseJson(json: Pojo): Pojo;
 
-    $formatJson(json: Pojo): Pojo;
+    $formatJson(json: Pojo, opt?: Pojo): Pojo;
     $parseJson(json: Pojo, opt?: ModelOptions): Pojo;
 
     $beforeValidate(jsonSchema: JSONSchema, json: Pojo, opt: ModelOptions): JSONSchema;
@@ -1831,14 +1869,7 @@ declare namespace Objection {
    * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
    */
   export type JSONSchemaTypeName =
-    | 'string'
-    | 'number'
-    | 'integer'
-    | 'boolean'
-    | 'object'
-    | 'array'
-    | 'null'
-    | string;
+    'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null' | string;
 
   export type JSONSchemaType = JSONSchemaArray[] | boolean | number | null | object | string;
 
@@ -1870,6 +1901,13 @@ declare namespace Objection {
     $schema?: JSONSchemaVersion;
     $comment?: string;
 
+    /**
+     * @see https://json-schema.org/draft/2019-09/release-notes
+     */
+    $defs?: {
+      [key: string]: JSONSchemaDefinition;
+    };
+
     /**
      * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1
      */