fix/4068 batchInsert correct definitions

test-tsd/batchInsert.test-d.ts

@@ -0,0 +1,47 @@
+import Knex from '../types';
+import { expectError, expectType } from 'tsd';
+import { clientConfig } from './common';
+
+const knex = Knex(clientConfig);
+
+// Use:
+// import Knex from 'knex'
+// when "esModuleInterop": true
+
+const main = async () => {
+  // default returning is number[]
+  expectType<number[]>(await knex.batchInsert('table', [{a: 2, id: 3}] as const, 12));
+
+  // allows any data
+  expectType<any[]>(await knex.batchInsert('table', [{a: 2, id: 3}] as any[], 12).returning('abc'));
+
+  // allows any data
+  expectType<any[]>(await knex.batchInsert('table', [{a: 2, id: 3}] as any, 12).returning('abc'));
+
+  // returning '*' allowed, return full record
+  expectType<Array<{a: boolean, id: number}>>(await knex.batchInsert('table', [{a: false, id: 3}], 12).returning('*'));
+
+  // one column for returning
+  expectType<Array<{aa2: string}>>(await knex.batchInsert('table', [{aa2: 'string', b: 3}], 12).returning('aa2'));
+
+  // many columns for returning
+  expectType<Array<{aa2: string, b: boolean}>>(await knex.batchInsert('table', [{aa2: 'string', b: false, c: 12}], 12).returning(['aa2', 'b']));
+
+  // assert bad column in returning gives error
+  expectError(
+    knex.batchInsert('table', [{aa2: 'string', b: false, c: 12}], 12)
+      .returning('bad_column')
+  );
+
+  // assert any bad column from returning list gives error
+  // tsd gives error on this, lol
+  /*expectError(
+    knex.batchInsert('table', [{aa2: 'string', b: false, c: 12}], 12)
+      .returning(['aa2', 'bad_column'])
+  );*/
+
+  // validates insert data
+  expectError(knex.batchInsert<{aa2: string, c: number}>('table', [{aa2: 'string', b: false, c: 12}], 12));
+
+  expectType<number[]>(await knex.batchInsert('table', [{a: 2, id: 3}] as const, 12).transacting(await knex.transaction()));
+};

types/index.d.ts

@@ -354,11 +354,15 @@ interface Knex<TRecord extends {} = any, TResult = unknown[]>
   initialize(config?: Knex.Config): void;
   destroy(callback: Function): void;
   destroy(): Promise<void>;
-  batchInsert(
+
+  batchInsert<TRecord2 = TRecord, TResult2 = number[]>(
     tableName: Knex.TableDescriptor,
-    data: readonly any[],
-    chunkSize?: number
-  ): Knex.QueryBuilder<TRecord, {}>;
+    data: TRecord2 extends Knex.CompositeTableType<unknown>
+      ? ReadonlyArray<Knex.ResolveTableType<TRecord2, 'insert'>>
+      : ReadonlyArray<Knex.DbRecordArr<TRecord2>>,
+    chunkSize?: number,
+  ): Knex.BatchInsertBuilder<TRecord2, TResult2>;
+
   schema: Knex.SchemaBuilder;
   queryBuilder<TRecord2 = TRecord, TResult2 = TResult>(): Knex.QueryBuilder<
     TRecord2,
@@ -1504,6 +1508,35 @@ declare namespace Knex {
       <TSrc extends string>(src: TSrc): Ref<TSrc, {[K in TSrc]: TSrc}>;
   }
 
+  interface BatchInsertBuilder<TRecord extends {} = any, TResult = number[]> extends Promise<ResolveResult<TResult>> {
+    transacting(trx: Transaction): this;
+    // see returning methods from QueryInterface
+    returning(column: '*'): BatchInsertBuilder<TRecord, DeferredKeySelection<TRecord, never>[]>;
+    returning<
+      TKey extends StrKey<ResolveTableType<TRecord>>,
+      TResult2 = DeferredIndex.Augment<
+        UnwrapArrayMember<TResult>,
+        ResolveTableType<TRecord>,
+        TKey
+        >[]
+      >(
+      column: TKey
+    ): BatchInsertBuilder<TRecord, TResult2>;
+    returning<
+      TKey extends StrKey<ResolveTableType<TRecord>>,
+      TResult2 = DeferredKeySelection.SetSingle<
+        DeferredKeySelection.Augment<UnwrapArrayMember<TResult>, ResolveTableType<TRecord>, TKey>,
+        false
+        >[]
+      >(
+      columns: readonly TKey[]
+    ): BatchInsertBuilder<TRecord, TResult2>;
+    // if data with specific type passed, exclude this method
+    returning<TResult2 = SafePartial<TRecord>[]>(
+      column: unknown extends TRecord ? string | readonly string[] : never
+    ): BatchInsertBuilder<TRecord, TResult2>;
+  }
+
   //
   // QueryBuilder
   //