connection: rewrote query execution, batching, added generic sqlite, added node/bun sqlite, aligned repo/mutator results

app/src/data/api/DataController.ts

@@ -3,9 +3,7 @@ import {
    DataPermissions,
    type EntityData,
    type EntityManager,
-   type MutatorResponse,
    type RepoQuery,
-   type RepositoryResponse,
    repoQuery,
 } from "data";
 import type { Handler } from "hono/types";
@@ -32,33 +30,6 @@ export class DataController extends Controller {
       return this.ctx.guard;
    }
 
-   repoResult<T extends RepositoryResponse<any> = RepositoryResponse>(
-      res: T,
-   ): Pick<T, "meta" | "data"> {
-      let meta: Partial<RepositoryResponse["meta"]> = {};
-
-      if ("meta" in res) {
-         const { query, ...rest } = res.meta;
-         meta = rest;
-         if (isDebug()) meta.query = query;
-      }
-
-      const template = { data: res.data, meta };
-
-      // @todo: this works but it breaks in FE (need to improve DataTable)
-      // filter empty
-      return Object.fromEntries(
-         Object.entries(template).filter(([_, v]) => typeof v !== "undefined" && v !== null),
-      ) as any;
-   }
-
-   mutatorResult(res: MutatorResponse | MutatorResponse<EntityData>) {
-      const template = { data: res.data };
-
-      // filter empty
-      return Object.fromEntries(Object.entries(template).filter(([_, v]) => v !== undefined));
-   }
-
    entityExists(entity: string) {
       try {
          return !!this.em.entity(entity);
@@ -257,7 +228,7 @@ export class DataController extends Controller {
 
             const where = c.req.valid("json") as any;
             const result = await this.em.repository(entity).count(where);
-            return c.json({ entity, count: result.count });
+            return c.json({ entity, ...result.data });
          },
       );
 
@@ -279,7 +250,7 @@ export class DataController extends Controller {
 
             const where = c.req.valid("json") as any;
             const result = await this.em.repository(entity).exists(where);
-            return c.json({ entity, exists: result.exists });
+            return c.json({ entity, ...result.data });
          },
       );
 
@@ -318,7 +289,7 @@ export class DataController extends Controller {
             const options = c.req.valid("query") as RepoQuery;
             const result = await this.em.repository(entity).findMany(options);
 
-            return c.json(this.repoResult(result), { status: result.data ? 200 : 404 });
+            return c.json(result, { status: result.data ? 200 : 404 });
          },
       );
 
@@ -347,7 +318,7 @@ export class DataController extends Controller {
             const options = c.req.valid("query") as RepoQuery;
             const result = await this.em.repository(entity).findId(id, options);
 
-            return c.json(this.repoResult(result), { status: result.data ? 200 : 404 });
+            return c.json(result, { status: result.data ? 200 : 404 });
          },
       );
 
@@ -380,7 +351,7 @@ export class DataController extends Controller {
                .repository(entity)
                .findManyByReference(id, reference, options);
 
-            return c.json(this.repoResult(result), { status: result.data ? 200 : 404 });
+            return c.json(result, { status: result.data ? 200 : 404 });
          },
       );
 
@@ -414,7 +385,7 @@ export class DataController extends Controller {
             const options = (await c.req.json()) as RepoQuery;
             const result = await this.em.repository(entity).findMany(options);
 
-            return c.json(this.repoResult(result), { status: result.data ? 200 : 404 });
+            return c.json(result, { status: result.data ? 200 : 404 });
          },
       );
 
@@ -440,11 +411,11 @@ export class DataController extends Controller {
 
             if (Array.isArray(body)) {
                const result = await this.em.mutator(entity).insertMany(body);
-               return c.json(this.mutatorResult(result), 201);
+               return c.json(result, 201);
             }
 
             const result = await this.em.mutator(entity).insertOne(body);
-            return c.json(this.mutatorResult(result), 201);
+            return c.json(result, 201);
          },
       );
 
@@ -475,7 +446,7 @@ export class DataController extends Controller {
             };
             const result = await this.em.mutator(entity).updateWhere(update, where);
 
-            return c.json(this.mutatorResult(result));
+            return c.json(result);
          },
       );
 
@@ -497,7 +468,7 @@ export class DataController extends Controller {
             const body = (await c.req.json()) as EntityData;
             const result = await this.em.mutator(entity).updateOne(id, body);
 
-            return c.json(this.mutatorResult(result));
+            return c.json(result);
          },
       );
 
@@ -517,7 +488,7 @@ export class DataController extends Controller {
             }
             const result = await this.em.mutator(entity).deleteOne(id);
 
-            return c.json(this.mutatorResult(result));
+            return c.json(result);
          },
       );
 
@@ -539,7 +510,7 @@ export class DataController extends Controller {
             const where = (await c.req.json()) as RepoQuery["where"];
             const result = await this.em.mutator(entity).deleteWhere(where);
 
-            return c.json(this.mutatorResult(result));
+            return c.json(result);
          },
       );
 

app/src/data/connection/Connection.ts

@@ -2,12 +2,15 @@ import {
    type AliasableExpression,
    type ColumnBuilderCallback,
    type ColumnDataType,
+   type Compilable,
+   type CompiledQuery,
    type DatabaseIntrospector,
    type Dialect,
    type Expression,
    type Kysely,
    type KyselyPlugin,
    type OnModifyForeignAction,
+   type QueryResult,
    type RawBuilder,
    type SelectQueryBuilder,
    type SelectQueryNode,
@@ -15,7 +18,8 @@ import {
    sql,
 } from "kysely";
 import type { BaseIntrospector, BaseIntrospectorConfig } from "./BaseIntrospector";
-import type { Constructor } from "core";
+import type { Constructor, DB } from "core";
+import { KyselyPluginRunner } from "data/plugins/KyselyPluginRunner";
 
 export type QB = SelectQueryBuilder<any, any, any>;
 
@@ -75,22 +79,44 @@ export type DbFunctions = {
    >;
 };
 
+export type ConnQuery = CompiledQuery | Compilable;
+
+export type ConnQueryResult<T extends ConnQuery> = T extends CompiledQuery<infer R>
+   ? QueryResult<R>
+   : T extends Compilable<infer R>
+     ? QueryResult<R>
+     : never;
+
+export type ConnQueryResults<T extends ConnQuery[]> = {
+   [K in keyof T]: ConnQueryResult<T[K]>;
+};
+
 const CONN_SYMBOL = Symbol.for("bknd:connection");
 
-export abstract class Connection<DB = any> {
+export type Features = {
+   batching: boolean;
+   softscans: boolean;
+};
+
+export abstract class Connection<Client = unknown> {
+   abstract name: string;
    protected initialized = false;
-   kysely: Kysely<DB>;
-   protected readonly supported = {
+   protected pluginRunner: KyselyPluginRunner;
+   protected readonly supported: Partial<Features> = {
       batching: false,
+      softscans: true,
    };
+   kysely: Kysely<DB>;
+   client!: Client;
 
    constructor(
-      kysely: Kysely<DB>,
+      kysely: Kysely<any>,
       public fn: Partial<DbFunctions> = {},
       protected plugins: KyselyPlugin[] = [],
    ) {
       this.kysely = kysely;
       this[CONN_SYMBOL] = true;
+      this.pluginRunner = new KyselyPluginRunner(plugins);
    }
 
    // @todo: consider moving constructor logic here, required by sqlocal
@@ -121,30 +147,46 @@ export abstract class Connection<DB = any> {
       return res.rows.length > 0;
    }
 
-   protected async batch<Queries extends QB[]>(
-      queries: [...Queries],
-   ): Promise<{
-      [K in keyof Queries]: Awaited<ReturnType<Queries[K]["execute"]>>;
-   }> {
-      throw new Error("Batching not supported");
+   protected async transformResultRows(result: any[]): Promise<any[]> {
+      return await this.pluginRunner.transformResultRows(result);
    }
 
-   async batchQuery<Queries extends QB[]>(
-      queries: [...Queries],
-   ): Promise<{
-      [K in keyof Queries]: Awaited<ReturnType<Queries[K]["execute"]>>;
-   }> {
-      // bypass if no client support
-      if (!this.supports("batching")) {
-         const data: any = [];
-         for (const q of queries) {
-            const result = await q.execute();
-            data.push(result);
-         }
-         return data;
-      }
+   /**
+    * Execute a query and return the result including all metadata
+    * returned from the dialect.
+    */
+   async executeQueries<O extends ConnQuery[]>(...qbs: O): Promise<ConnQueryResults<O>> {
+      return Promise.all(qbs.map(async (qb) => await this.kysely.executeQuery(qb))) as any;
+   }
 
-      return await this.batch(queries);
+   async executeQuery<O extends ConnQuery>(qb: O): Promise<ConnQueryResult<O>> {
+      const res = await this.executeQueries(qb);
+      return res[0] as any;
+   }
+
+   protected getCompiled(...qbs: ConnQuery[]): CompiledQuery[] {
+      return qbs.map((qb) => {
+         if ("compile" in qb) {
+            return qb.compile();
+         }
+         return qb;
+      });
+   }
+
+   protected async withTransformedRows<
+      Key extends string = "rows",
+      O extends { [K in Key]: any[] }[] = [],
+   >(result: O, _key?: Key): Promise<O> {
+      return (await Promise.all(
+         result.map(async (row) => {
+            const key = _key ?? "rows";
+            const { [key]: rows, ...r } = row;
+            return {
+               ...r,
+               rows: await this.transformResultRows(rows),
+            };
+         }),
+      )) as any;
    }
 
    protected validateFieldSpecType(type: string): type is FieldSpec["type"] {

app/src/data/connection/connection-test-suite.ts

@@ -0,0 +1,187 @@
+import type { TestRunner } from "core/test";
+import { Connection, type FieldSpec } from "./Connection";
+
+export function connectionTestSuite(
+   testRunner: TestRunner,
+   {
+      makeConnection,
+      rawDialectDetails,
+   }: {
+      makeConnection: () => Connection;
+      rawDialectDetails: string[];
+   },
+) {
+   const { test, expect, describe } = testRunner;
+
+   test("pings", async () => {
+      const connection = makeConnection();
+      const res = await connection.ping();
+      expect(res).toBe(true);
+   });
+
+   test("initializes", async () => {
+      const connection = makeConnection();
+      await connection.init();
+      // @ts-expect-error
+      expect(connection.initialized).toBe(true);
+      expect(connection.client).toBeDefined();
+   });
+
+   test("isConnection", async () => {
+      const connection = makeConnection();
+      expect(Connection.isConnection(connection)).toBe(true);
+   });
+
+   test("getFieldSchema", async () => {
+      const c = makeConnection();
+      const specToNode = (spec: FieldSpec) => {
+         // @ts-expect-error
+         const schema = c.kysely.schema.createTable("test").addColumn(...c.getFieldSchema(spec));
+         return schema.toOperationNode();
+      };
+
+      {
+         // primary
+         const node = specToNode({
+            type: "integer",
+            name: "id",
+            primary: true,
+         });
+         const col = node.columns[0]!;
+         expect(col.primaryKey).toBe(true);
+         expect(col.notNull).toBe(true);
+      }
+
+      {
+         // normal
+         const node = specToNode({
+            type: "text",
+            name: "text",
+         });
+         const col = node.columns[0]!;
+         expect(!col.primaryKey).toBe(true);
+         expect(!col.notNull).toBe(true);
+      }
+
+      {
+         // nullable (expect to be same as normal)
+         const node = specToNode({
+            type: "text",
+            name: "text",
+            nullable: true,
+         });
+         const col = node.columns[0]!;
+         expect(!col.primaryKey).toBe(true);
+         expect(!col.notNull).toBe(true);
+      }
+   });
+
+   describe("schema", async () => {
+      const connection = makeConnection();
+      const fields = [
+         {
+            type: "integer",
+            name: "id",
+            primary: true,
+         },
+         {
+            type: "text",
+            name: "text",
+         },
+         {
+            type: "json",
+            name: "json",
+         },
+      ] as const satisfies FieldSpec[];
+
+      let b = connection.kysely.schema.createTable("test");
+      for (const field of fields) {
+         // @ts-expect-error
+         b = b.addColumn(...connection.getFieldSchema(field));
+      }
+      await b.execute();
+
+      // add index
+      await connection.kysely.schema.createIndex("test_index").on("test").columns(["id"]).execute();
+
+      test("executes query", async () => {
+         await connection.kysely
+            .insertInto("test")
+            .values({ id: 1, text: "test", json: JSON.stringify({ a: 1 }) })
+            .execute();
+
+         const expected = { id: 1, text: "test", json: { a: 1 } };
+
+         const qb = connection.kysely.selectFrom("test").selectAll();
+         const res = await connection.executeQuery(qb);
+         expect(res.rows).toEqual([expected]);
+         expect(rawDialectDetails.every((detail) => detail in res)).toBe(true);
+
+         {
+            const res = await connection.executeQueries(qb, qb);
+            expect(res.length).toBe(2);
+            res.map((r) => {
+               expect(r.rows).toEqual([expected]);
+               expect(rawDialectDetails.every((detail) => detail in r)).toBe(true);
+            });
+         }
+      });
+
+      test("introspects", async () => {
+         const tables = await connection.getIntrospector().getTables({
+            withInternalKyselyTables: false,
+         });
+         const clean = tables.map((t) => ({
+            ...t,
+            columns: t.columns.map((c) => ({
+               ...c,
+               dataType: undefined,
+            })),
+         }));
+
+         expect(clean).toEqual([
+            {
+               name: "test",
+               isView: false,
+               columns: [
+                  {
+                     name: "id",
+                     dataType: undefined,
+                     isNullable: false,
+                     isAutoIncrementing: true,
+                     hasDefaultValue: false,
+                  },
+                  {
+                     name: "text",
+                     dataType: undefined,
+                     isNullable: true,
+                     isAutoIncrementing: false,
+                     hasDefaultValue: false,
+                  },
+                  {
+                     name: "json",
+                     dataType: undefined,
+                     isNullable: true,
+                     isAutoIncrementing: false,
+                     hasDefaultValue: false,
+                  },
+               ],
+            },
+         ]);
+      });
+
+      expect(await connection.getIntrospector().getIndices()).toEqual([
+         {
+            name: "test_index",
+            table: "test",
+            isUnique: false,
+            columns: [
+               {
+                  name: "id",
+                  order: 0,
+               },
+            ],
+         },
+      ]);
+   });
+}

app/src/data/connection/sqlite/GenericSqliteConnection.ts

@@ -0,0 +1,37 @@
+import type { KyselyPlugin } from "kysely";
+import {
+   type IGenericSqlite,
+   type OnCreateConnection,
+   type Promisable,
+   parseBigInt,
+   buildQueryFn,
+   GenericSqliteDialect,
+} from "kysely-generic-sqlite";
+import { SqliteConnection } from "./SqliteConnection";
+
+export type GenericSqliteConnectionConfig = {
+   name: string;
+   additionalPlugins?: KyselyPlugin[];
+   excludeTables?: string[];
+   onCreateConnection?: OnCreateConnection;
+};
+
+export { parseBigInt, buildQueryFn, GenericSqliteDialect, type IGenericSqlite };
+
+export class GenericSqliteConnection<DB = unknown> extends SqliteConnection<DB> {
+   override name = "generic-sqlite";
+
+   constructor(
+      db: DB,
+      executor: () => Promisable<IGenericSqlite>,
+      config?: GenericSqliteConnectionConfig,
+   ) {
+      super({
+         dialect: GenericSqliteDialect,
+         dialectArgs: [executor, config?.onCreateConnection],
+         additionalPlugins: config?.additionalPlugins,
+         excludeTables: config?.excludeTables,
+      });
+      this.client = db;
+   }
+}

app/src/data/connection/sqlite/LibsqlConnection.spec.ts

@@ -0,0 +1,11 @@
+import { connectionTestSuite } from "../connection-test-suite";
+import { LibsqlConnection } from "./LibsqlConnection";
+import { bunTestRunner } from "adapter/bun/test";
+import { describe } from "bun:test";
+
+describe("LibsqlConnection", () => {
+   connectionTestSuite(bunTestRunner, {
+      makeConnection: () => new LibsqlConnection({ url: ":memory:" }),
+      rawDialectDetails: ["rowsAffected", "lastInsertRowid"],
+   });
+});

app/src/data/connection/sqlite/LibsqlConnection.ts

@@ -1,40 +1,26 @@
-import { type Client, type Config, type InStatement, createClient } from "@libsql/client";
+import { createClient, type Client, type Config, type InStatement } from "@libsql/client";
 import { LibsqlDialect } from "@libsql/kysely-libsql";
-import { FilterNumericKeysPlugin } from "data/plugins/FilterNumericKeysPlugin";
-import { KyselyPluginRunner } from "data/plugins/KyselyPluginRunner";
-import { type DatabaseIntrospector, Kysely, ParseJSONResultsPlugin } from "kysely";
-import type { QB } from "../Connection";
-import { SqliteConnection } from "./SqliteConnection";
-import { SqliteIntrospector } from "./SqliteIntrospector";
 import { $console } from "core";
+import { FilterNumericKeysPlugin } from "data/plugins/FilterNumericKeysPlugin";
+import type { ConnQuery, ConnQueryResults } from "../Connection";
+import { SqliteConnection } from "./SqliteConnection";
 
 export const LIBSQL_PROTOCOLS = ["wss", "https", "libsql"] as const;
 export type LibSqlCredentials = Config & {
    protocol?: (typeof LIBSQL_PROTOCOLS)[number];
 };
 
-const plugins = [new FilterNumericKeysPlugin(), new ParseJSONResultsPlugin()];
-
-class CustomLibsqlDialect extends LibsqlDialect {
-   override createIntrospector(db: Kysely<any>): DatabaseIntrospector {
-      return new SqliteIntrospector(db, {
-         excludeTables: ["libsql_wasm_func_table"],
-         plugins,
-      });
-   }
-}
-
-export class LibsqlConnection extends SqliteConnection {
-   private client: Client;
+export class LibsqlConnection extends SqliteConnection<Client> {
+   override name = "libsql";
    protected override readonly supported = {
       batching: true,
+      softscans: true,
    };
 
    constructor(client: Client);
    constructor(credentials: LibSqlCredentials);
    constructor(clientOrCredentials: Client | LibSqlCredentials) {
       let client: Client;
-      let batching_enabled = true;
       if (clientOrCredentials && "url" in clientOrCredentials) {
          let { url, authToken, protocol } = clientOrCredentials;
          if (protocol && LIBSQL_PROTOCOLS.includes(protocol)) {
@@ -48,45 +34,25 @@ export class LibsqlConnection extends SqliteConnection {
          client = clientOrCredentials;
       }
 
-      const kysely = new Kysely({
-         // @ts-expect-error libsql has type issues
-         dialect: new CustomLibsqlDialect({ client }),
-         plugins,
+      super({
+         excludeTables: ["libsql_wasm_func_table"],
+         dialect: LibsqlDialect,
+         dialectArgs: [{ client }],
+         additionalPlugins: [new FilterNumericKeysPlugin()],
       });
 
-      super(kysely, {}, plugins);
       this.client = client;
-      this.supported.batching = batching_enabled;
    }
 
-   getClient(): Client {
-      return this.client;
-   }
-
-   protected override async batch<Queries extends QB[]>(
-      queries: [...Queries],
-   ): Promise<{
-      [K in keyof Queries]: Awaited<ReturnType<Queries[K]["execute"]>>;
-   }> {
-      const stms: InStatement[] = queries.map((q) => {
-         const compiled = q.compile();
+   override async executeQueries<O extends ConnQuery[]>(...qbs: O): Promise<ConnQueryResults<O>> {
+      const compiled = this.getCompiled(...qbs);
+      const stms: InStatement[] = compiled.map((q) => {
          return {
-            sql: compiled.sql,
-            args: compiled.parameters as any[],
+            sql: q.sql,
+            args: q.parameters as any[],
          };
       });
 
-      const res = await this.client.batch(stms);
-
-      // let it run through plugins
-      const kyselyPlugins = new KyselyPluginRunner(this.plugins);
-
-      const data: any = [];
-      for (const r of res) {
-         const rows = await kyselyPlugins.transformResultRows(r.rows);
-         data.push(rows);
-      }
-
-      return data;
+      return this.withTransformedRows(await this.client.batch(stms)) as any;
    }
 }

app/src/data/connection/sqlite/SqliteConnection.ts

@@ -1,16 +1,49 @@
-import type { ColumnDataType, ColumnDefinitionBuilder, Kysely, KyselyPlugin } from "kysely";
+import {
+   ParseJSONResultsPlugin,
+   type ColumnDataType,
+   type ColumnDefinitionBuilder,
+   type Dialect,
+   Kysely,
+   type KyselyPlugin,
+} from "kysely";
 import { jsonArrayFrom, jsonBuildObject, jsonObjectFrom } from "kysely/helpers/sqlite";
 import { Connection, type DbFunctions, type FieldSpec, type SchemaResponse } from "../Connection";
+import type { Constructor } from "core";
+import { customIntrospector } from "../Connection";
+import { SqliteIntrospector } from "./SqliteIntrospector";
+
+export type SqliteConnectionConfig<
+   CustomDialect extends Constructor<Dialect> = Constructor<Dialect>,
+> = {
+   excludeTables?: string[];
+   dialect: CustomDialect;
+   dialectArgs?: ConstructorParameters<CustomDialect>;
+   additionalPlugins?: KyselyPlugin[];
+   customFn?: Partial<DbFunctions>;
+};
+
+export abstract class SqliteConnection<Client = unknown> extends Connection<Client> {
+   override name = "sqlite";
+
+   constructor(config: SqliteConnectionConfig) {
+      const { excludeTables, dialect, dialectArgs = [], additionalPlugins } = config;
+      const plugins = [new ParseJSONResultsPlugin(), ...(additionalPlugins ?? [])];
+
+      const kysely = new Kysely({
+         dialect: customIntrospector(dialect, SqliteIntrospector, {
+            excludeTables,
+            plugins,
+         }).create(...dialectArgs),
+         plugins,
+      });
 
-export class SqliteConnection extends Connection {
-   constructor(kysely: Kysely<any>, fn: Partial<DbFunctions> = {}, plugins: KyselyPlugin[] = []) {
       super(
          kysely,
          {
-            ...fn,
             jsonArrayFrom,
             jsonObjectFrom,
             jsonBuildObject,
+            ...(config.customFn ?? {}),
          },
          plugins,
       );
@@ -43,7 +76,7 @@ export class SqliteConnection extends Connection {
                if (spec.onUpdate) relCol = relCol.onUpdate(spec.onUpdate);
                return relCol;
             }
-            return spec.nullable ? col : col.notNull();
+            return col;
          },
       ] as const;
    }

app/src/data/connection/sqlite/SqliteLocalConnection.ts

@@ -1,31 +1,14 @@
-import {
-   type DatabaseIntrospector,
-   Kysely,
-   ParseJSONResultsPlugin,
-   type SqliteDatabase,
-   SqliteDialect,
-} from "kysely";
+import { type SqliteDatabase, SqliteDialect } from "kysely";
 import { SqliteConnection } from "./SqliteConnection";
-import { SqliteIntrospector } from "./SqliteIntrospector";
 
-const plugins = [new ParseJSONResultsPlugin()];
+export class SqliteLocalConnection extends SqliteConnection<SqliteDatabase> {
+   override name = "sqlite-local";
 
-class CustomSqliteDialect extends SqliteDialect {
-   override createIntrospector(db: Kysely<any>): DatabaseIntrospector {
-      return new SqliteIntrospector(db, {
-         excludeTables: ["test_table"],
-         plugins,
+   constructor(database: SqliteDatabase) {
+      super({
+         dialect: SqliteDialect,
+         dialectArgs: [{ database }],
       });
-   }
-}
-
-export class SqliteLocalConnection extends SqliteConnection {
-   constructor(private database: SqliteDatabase) {
-      const kysely = new Kysely({
-         dialect: new CustomSqliteDialect({ database }),
-         plugins,
-      });
-
-      super(kysely, {}, plugins);
+      this.client = database;
    }
 }

app/src/data/entities/EntityManager.ts

@@ -207,8 +207,9 @@ export class EntityManager<TBD extends object = DefaultDB> {
 
    repository<E extends Entity | keyof TBD | string>(
       entity: E,
+      opts: Omit<RepositoryOptions, "emgr"> = {},
    ): Repository<TBD, EntitySchema<TBD, E>> {
-      return this.repo(entity);
+      return this.repo(entity, opts);
    }
 
    repo<E extends Entity | keyof TBD | string>(

app/src/data/entities/Result.ts

@@ -0,0 +1,126 @@
+import { isDebug } from "core";
+import { pick } from "core/utils";
+import type { Connection } from "data/connection";
+import type {
+   Compilable,
+   CompiledQuery,
+   QueryResult as KyselyQueryResult,
+   SelectQueryBuilder,
+} from "kysely";
+
+export type ResultHydrator<T = any> = (rows: T[]) => any;
+export type ResultOptions<T = any> = {
+   hydrator?: ResultHydrator<T>;
+   beforeExecute?: (compiled: CompiledQuery) => void | Promise<void>;
+   onError?: (error: Error) => void | Promise<void>;
+   single?: boolean;
+};
+export type ResultJSON<T = any> = {
+   data: T;
+   meta: {
+      items: number;
+      time: number;
+      sql?: string;
+      parameters?: any[];
+      [key: string]: any;
+   };
+};
+
+export interface QueryResult<T = any> extends Omit<KyselyQueryResult<T>, "rows"> {
+   time: number;
+   items: number;
+   data: T;
+   rows: unknown[];
+   sql: string;
+   parameters: any[];
+   count?: number;
+   total?: number;
+}
+
+export class Result<T = unknown> {
+   results: QueryResult<T>[] = [];
+   time: number = 0;
+
+   constructor(
+      protected conn: Connection,
+      protected options: ResultOptions<T> = {},
+   ) {}
+
+   get(): QueryResult<T> {
+      if (!this.results) {
+         throw new Error("Result not executed");
+      }
+
+      if (Array.isArray(this.results)) {
+         return (this.results ?? []) as any;
+      }
+
+      return this.results[0] as any;
+   }
+
+   first(): QueryResult<T> {
+      const res = this.get();
+      const first = Array.isArray(res) ? res[0] : res;
+      return first ?? ({} as any);
+   }
+
+   get sql() {
+      return this.first().sql;
+   }
+
+   get parameters() {
+      return this.first().parameters;
+   }
+
+   get data() {
+      if (this.options.single) {
+         return this.first().data?.[0];
+      }
+
+      return this.first().data ?? [];
+   }
+
+   async execute(qb: Compilable | Compilable[]) {
+      const qbs = Array.isArray(qb) ? qb : [qb];
+
+      for (const qb of qbs) {
+         const compiled = qb.compile();
+         await this.options.beforeExecute?.(compiled);
+         try {
+            const start = performance.now();
+            const res = await this.conn.executeQuery(compiled);
+            this.time = Number.parseFloat((performance.now() - start).toFixed(2));
+            this.results.push({
+               ...res,
+               data: this.options.hydrator?.(res.rows as T[]),
+               items: res.rows.length,
+               time: this.time,
+               sql: compiled.sql,
+               parameters: [...compiled.parameters],
+            });
+         } catch (e) {
+            if (this.options.onError) {
+               await this.options.onError(e as Error);
+            } else {
+               throw e;
+            }
+         }
+      }
+
+      return this;
+   }
+
+   protected additionalMetaKeys(): string[] {
+      return [];
+   }
+
+   toJSON(): ResultJSON<T> {
+      const { rows, data, ...metaRaw } = this.first();
+      const keys = isDebug() ? ["items", "time", "sql", "parameters"] : ["items", "time"];
+      const meta = pick(metaRaw, [...keys, ...this.additionalMetaKeys()] as any);
+      return {
+         data: this.data,
+         meta,
+      };
+   }
+}

app/src/data/entities/index.ts

@@ -1,6 +1,6 @@
 export * from "./Entity";
 export * from "./EntityManager";
-export * from "./Mutator";
+export * from "./mutation/Mutator";
 export * from "./query/Repository";
 export * from "./query/WhereBuilder";
 export * from "./query/WithBuilder";

app/src/data/entities/mutation/Mutator.ts

@@ -1,12 +1,13 @@
 import { $console, type DB as DefaultDB, type PrimaryFieldType } from "core";
 import { type EmitsEvents, EventManager } from "core/events";
 import type { DeleteQueryBuilder, InsertQueryBuilder, UpdateQueryBuilder } from "kysely";
-import { type TActionContext, WhereBuilder } from "..";
-import type { Entity, EntityData, EntityManager } from "../entities";
-import { InvalidSearchParamsException } from "../errors";
-import { MutatorEvents } from "../events";
-import { RelationMutator } from "../relations";
-import type { RepoQuery } from "../server/query";
+import { type TActionContext, WhereBuilder } from "../..";
+import type { Entity, EntityData, EntityManager } from "../../entities";
+import { InvalidSearchParamsException } from "../../errors";
+import { MutatorEvents } from "../../events";
+import { RelationMutator } from "../../relations";
+import type { RepoQuery } from "../../server/query";
+import { MutatorResult, type MutatorResultOptions } from "./MutatorResult";
 
 type MutatorQB =
    | InsertQueryBuilder<any, any, any>
@@ -17,14 +18,6 @@ type MutatorUpdateOrDelete =
    | UpdateQueryBuilder<any, any, any, any>
    | DeleteQueryBuilder<any, any, any>;
 
-export type MutatorResponse<T = EntityData[]> = {
-   entity: Entity;
-   sql: string;
-   parameters: any[];
-   result: EntityData[];
-   data: T;
-};
-
 export class Mutator<
    TBD extends object = DefaultDB,
    TB extends keyof TBD = any,
@@ -103,35 +96,18 @@ export class Mutator<
       return validatedData as Given;
    }
 
-   protected async many(qb: MutatorQB): Promise<MutatorResponse> {
-      const entity = this.entity;
-      const { sql, parameters } = qb.compile();
-
-      try {
-         const result = await qb.execute();
-
-         const data = this.em.hydrate(entity.name, result) as EntityData[];
-
-         return {
-            entity,
-            sql,
-            parameters: [...parameters],
-            result: result,
-            data,
-         };
-      } catch (e) {
-         // @todo: redact
-         $console.error("[Error in query]", sql);
-         throw e;
-      }
+   protected async performQuery<T = EntityData[]>(
+      qb: MutatorQB,
+      opts?: MutatorResultOptions,
+   ): Promise<MutatorResult<T>> {
+      const result = new MutatorResult(this.em, this.entity, {
+         silent: false,
+         ...opts,
+      });
+      return (await result.execute(qb)) as any;
    }
 
-   protected async single(qb: MutatorQB): Promise<MutatorResponse<EntityData>> {
-      const { data, ...response } = await this.many(qb);
-      return { ...response, data: data[0]! };
-   }
-
-   async insertOne(data: Input): Promise<MutatorResponse<Output>> {
+   async insertOne(data: Input): Promise<MutatorResult<Output>> {
       const entity = this.entity;
       if (entity.type === "system" && this.__unstable_disable_system_entity_creation) {
          throw new Error(`Creation of system entity "${entity.name}" is disabled`);
@@ -174,7 +150,7 @@ export class Mutator<
          .values(validatedData)
          .returning(entity.getSelect());
 
-      const res = await this.single(query);
+      const res = await this.performQuery(query, { single: true });
 
       await this.emgr.emit(
          new Mutator.Events.MutatorInsertAfter({ entity, data: res.data, changed: validatedData }),
@@ -183,7 +159,7 @@ export class Mutator<
       return res as any;
    }
 
-   async updateOne(id: PrimaryFieldType, data: Partial<Input>): Promise<MutatorResponse<Output>> {
+   async updateOne(id: PrimaryFieldType, data: Partial<Input>): Promise<MutatorResult<Output>> {
       const entity = this.entity;
       if (!id) {
          throw new Error("ID must be provided for update");
@@ -206,7 +182,7 @@ export class Mutator<
          .where(entity.id().name, "=", id)
          .returning(entity.getSelect());
 
-      const res = await this.single(query);
+      const res = await this.performQuery(query, { single: true });
 
       await this.emgr.emit(
          new Mutator.Events.MutatorUpdateAfter({
@@ -220,7 +196,7 @@ export class Mutator<
       return res as any;
    }
 
-   async deleteOne(id: PrimaryFieldType): Promise<MutatorResponse<Output>> {
+   async deleteOne(id: PrimaryFieldType): Promise<MutatorResult<Output>> {
       const entity = this.entity;
       if (!id) {
          throw new Error("ID must be provided for deletion");
@@ -233,7 +209,7 @@ export class Mutator<
          .where(entity.id().name, "=", id)
          .returning(entity.getSelect());
 
-      const res = await this.single(query);
+      const res = await this.performQuery(query, { single: true });
 
       await this.emgr.emit(
          new Mutator.Events.MutatorDeleteAfter({ entity, entityId: id, data: res.data }),
@@ -286,7 +262,7 @@ export class Mutator<
    }
 
    // @todo: decide whether entries should be deleted all at once or one by one (for events)
-   async deleteWhere(where: RepoQuery["where"]): Promise<MutatorResponse<Output[]>> {
+   async deleteWhere(where: RepoQuery["where"]): Promise<MutatorResult<Output[]>> {
       const entity = this.entity;
 
       // @todo: add a way to delete all by adding force?
@@ -298,13 +274,13 @@ export class Mutator<
          entity.getSelect(),
       );
 
-      return (await this.many(qb)) as any;
+      return await this.performQuery(qb);
    }
 
    async updateWhere(
       data: Partial<Input>,
       where: RepoQuery["where"],
-   ): Promise<MutatorResponse<Output[]>> {
+   ): Promise<MutatorResult<Output[]>> {
       const entity = this.entity;
       const validatedData = await this.getValidatedData(data, "update");
 
@@ -317,10 +293,10 @@ export class Mutator<
          .set(validatedData as any)
          .returning(entity.getSelect());
 
-      return (await this.many(query)) as any;
+      return await this.performQuery(query);
    }
 
-   async insertMany(data: Input[]): Promise<MutatorResponse<Output[]>> {
+   async insertMany(data: Input[]): Promise<MutatorResult<Output[]>> {
       const entity = this.entity;
       if (entity.type === "system" && this.__unstable_disable_system_entity_creation) {
          throw new Error(`Creation of system entity "${entity.name}" is disabled`);
@@ -352,6 +328,6 @@ export class Mutator<
          .values(validated)
          .returning(entity.getSelect());
 
-      return (await this.many(query)) as any;
+      return await this.performQuery(query);
    }
 }

app/src/data/entities/mutation/MutatorResult.ts

@@ -0,0 +1,33 @@
+import { $console } from "core/console";
+import type { Entity, EntityData } from "../Entity";
+import type { EntityManager } from "../EntityManager";
+import { Result, type ResultJSON, type ResultOptions } from "../Result";
+
+export type MutatorResultOptions = ResultOptions & {
+   silent?: boolean;
+};
+
+export type MutatorResultJSON<T = EntityData[]> = ResultJSON<T>;
+
+export class MutatorResult<T = EntityData[]> extends Result<T> {
+   constructor(
+      protected em: EntityManager<any>,
+      public entity: Entity,
+      options?: MutatorResultOptions,
+   ) {
+      super(em.connection, {
+         hydrator: (rows) => em.hydrate(entity.name, rows as any),
+         beforeExecute: (compiled) => {
+            if (!options?.silent) {
+               $console.debug(`[Mutation]\n${compiled.sql}\n`, compiled.parameters);
+            }
+         },
+         onError: (error) => {
+            if (!options?.silent) {
+               $console.error("[ERROR] Mutator:", error.message);
+            }
+         },
+         ...options,
+      });
+   }
+}

app/src/data/entities/query/Repository.ts

@@ -13,37 +13,11 @@ import {
    WithBuilder,
 } from "../index";
 import { JoinBuilder } from "./JoinBuilder";
-import { ensureInt } from "core/utils";
+import { RepositoryResult, type RepositoryResultOptions } from "./RepositoryResult";
+import type { ResultOptions } from "../Result";
 
 export type RepositoryQB = SelectQueryBuilder<any, any, any>;
 
-export type RepositoryRawResponse = {
-   sql: string;
-   parameters: any[];
-   result: EntityData[];
-};
-export type RepositoryResponse<T = EntityData[]> = RepositoryRawResponse & {
-   entity: Entity;
-   data: T;
-   meta: {
-      items: number;
-      total?: number;
-      count?: number;
-      time?: number;
-      query?: {
-         sql: string;
-         parameters: readonly any[];
-      };
-   };
-};
-
-export type RepositoryCountResponse = RepositoryRawResponse & {
-   count: number;
-};
-export type RepositoryExistsResponse = RepositoryRawResponse & {
-   exists: boolean;
-};
-
 export type RepositoryOptions = {
    silent?: boolean;
    includeCounts?: boolean;
@@ -182,126 +156,18 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       return validated;
    }
 
-   protected async executeQb(qb: RepositoryQB) {
-      const compiled = qb.compile();
-      if (this.options?.silent !== true) {
-         $console.debug(`Repository: query\n${compiled.sql}\n`, compiled.parameters);
-      }
-
-      let result: any;
-      try {
-         result = await qb.execute();
-      } catch (e) {
-         if (this.options?.silent !== true) {
-            if (e instanceof Error) {
-               $console.error("[ERROR] Repository.executeQb", e.message);
-            }
-
-            throw e;
-         }
-      }
-
-      return {
-         result,
-         sql: compiled.sql,
-         parameters: [...compiled.parameters],
-      };
-   }
-
-   protected async performQuery(qb: RepositoryQB): Promise<RepositoryResponse> {
-      const entity = this.entity;
-      const compiled = qb.compile();
-
-      const payload = {
-         entity,
-         sql: compiled.sql,
-         parameters: [...compiled.parameters],
-         result: [],
-         data: [],
-         meta: {
-            total: 0,
-            count: 0,
-            items: 0,
-            time: 0,
-            query: { sql: compiled.sql, parameters: compiled.parameters },
-         },
-      };
-
-      // don't batch (add counts) if `includeCounts` is set to false
-      // or when explicitly set to true and batching is not supported
-      if (
-         this.options?.includeCounts === false ||
-         (this.options?.includeCounts === true && !this.em.connection.supports("batching"))
-      ) {
-         const start = performance.now();
-         const res = await this.executeQb(qb);
-         const time = Number.parseFloat((performance.now() - start).toFixed(2));
-         const result = res.result ?? [];
-         const data = this.em.hydrate(entity.name, result);
-
-         return {
-            ...payload,
-            result,
-            data,
-            meta: {
-               ...payload.meta,
-               total: undefined,
-               count: undefined,
-               items: data.length,
-               time,
-            },
-         };
-      }
-
-      if (this.options?.silent !== true) {
-         $console.debug(`Repository: query\n${compiled.sql}\n`, compiled.parameters);
-      }
-
-      const selector = (as = "count") => this.conn.fn.countAll<number>().as(as);
-      const countQuery = qb
-         .clearSelect()
-         .select(selector())
-         .clearLimit()
-         .clearOffset()
-         .clearGroupBy()
-         .clearOrderBy();
-      const totalQuery = this.conn.selectFrom(entity.name).select(selector());
-
-      try {
-         const start = performance.now();
-         const [_count, _total, result] = await this.em.connection.batchQuery([
-            countQuery,
-            totalQuery,
-            qb,
-         ]);
-
-         const time = Number.parseFloat((performance.now() - start).toFixed(2));
-         const data = this.em.hydrate(entity.name, result);
-
-         return {
-            ...payload,
-            result,
-            data,
-            meta: {
-               ...payload.meta,
-               // parsing is important since pg returns string
-               total: ensureInt(_total[0]?.count),
-               count: ensureInt(_count[0]?.count),
-               items: result.length,
-               time,
-            },
-         };
-      } catch (e) {
-         if (this.options?.silent !== true) {
-            if (e instanceof Error) {
-               $console.error("[ERROR] Repository.performQuery", e.message);
-            }
-
-            throw e;
-         } else {
-            return payload;
-         }
-      }
+   protected async performQuery<T = EntityData[]>(
+      qb: RepositoryQB,
+      opts?: RepositoryResultOptions,
+      execOpts?: { includeCounts?: boolean },
+   ): Promise<RepositoryResult<T>> {
+      const result = new RepositoryResult(this.em, this.entity, {
+         silent: this.options.silent,
+         ...opts,
+      });
+      return (await result.execute(qb, {
+         includeCounts: execOpts?.includeCounts ?? this.options.includeCounts,
+      })) as any;
    }
 
    private async triggerFindBefore(entity: Entity, options: RepoQuery): Promise<void> {
@@ -319,7 +185,7 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
    ): Promise<void> {
       if (options.limit === 1) {
          await this.emgr.emit(
-            new Repository.Events.RepositoryFindOneAfter({ entity, options, data: data[0]! }),
+            new Repository.Events.RepositoryFindOneAfter({ entity, options, data }),
          );
       } else {
          await this.emgr.emit(
@@ -331,12 +197,11 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
    protected async single(
       qb: RepositoryQB,
       options: RepoQuery,
-   ): Promise<RepositoryResponse<EntityData>> {
+   ): Promise<RepositoryResult<TBD[TB] | undefined>> {
       await this.triggerFindBefore(this.entity, options);
-      const { data, ...response } = await this.performQuery(qb);
-
-      await this.triggerFindAfter(this.entity, options, data);
-      return { ...response, data: data[0]! };
+      const result = await this.performQuery(qb, { single: true });
+      await this.triggerFindAfter(this.entity, options, result.data);
+      return result as any;
    }
 
    addOptionsToQueryBuilder(
@@ -413,7 +278,7 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
    async findId(
       id: PrimaryFieldType,
       _options?: Partial<Omit<RepoQuery, "where" | "limit" | "offset">>,
-   ): Promise<RepositoryResponse<TBD[TB] | undefined>> {
+   ): Promise<RepositoryResult<TBD[TB] | undefined>> {
       const { qb, options } = this.buildQuery(
          {
             ..._options,
@@ -429,7 +294,7 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
    async findOne(
       where: RepoQuery["where"],
       _options?: Partial<Omit<RepoQuery, "where" | "limit" | "offset">>,
-   ): Promise<RepositoryResponse<TBD[TB] | undefined>> {
+   ): Promise<RepositoryResult<TBD[TB] | undefined>> {
       const { qb, options } = this.buildQuery({
          ..._options,
          where,
@@ -439,7 +304,7 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       return (await this.single(qb, options)) as any;
    }
 
-   async findMany(_options?: Partial<RepoQuery>): Promise<RepositoryResponse<TBD[TB][]>> {
+   async findMany(_options?: Partial<RepoQuery>): Promise<RepositoryResult<TBD[TB][]>> {
       const { qb, options } = this.buildQuery(_options);
       await this.triggerFindBefore(this.entity, options);
 
@@ -454,7 +319,7 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       id: PrimaryFieldType,
       reference: string,
       _options?: Partial<Omit<RepoQuery, "limit" | "offset">>,
-   ): Promise<RepositoryResponse<EntityData>> {
+   ): Promise<RepositoryResult<EntityData>> {
       const entity = this.entity;
       const listable_relations = this.em.relations.listableRelationsOf(entity);
       const relation = listable_relations.find((r) => r.ref(reference).reference === reference);
@@ -482,10 +347,10 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
          },
       };
 
-      return this.cloneFor(newEntity).findMany(findManyOptions);
+      return this.cloneFor(newEntity).findMany(findManyOptions) as any;
    }
 
-   async count(where?: RepoQuery["where"]): Promise<RepositoryCountResponse> {
+   async count(where?: RepoQuery["where"]): Promise<RepositoryResult<{ count: number }>> {
       const entity = this.entity;
       const options = this.getValidOptions({ where });
 
@@ -497,17 +362,18 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
          qb = WhereBuilder.addClause(qb, options.where);
       }
 
-      const { result, ...compiled } = await this.executeQb(qb);
-
-      return {
-         sql: compiled.sql,
-         parameters: [...compiled.parameters],
-         result,
-         count: result[0]?.count ?? 0,
-      };
+      return await this.performQuery(
+         qb,
+         {
+            hydrator: (rows) => ({ count: rows[0]?.count ?? 0 }),
+         },
+         { includeCounts: false },
+      );
    }
 
-   async exists(where: Required<RepoQuery>["where"]): Promise<RepositoryExistsResponse> {
+   async exists(
+      where: Required<RepoQuery>["where"],
+   ): Promise<RepositoryResult<{ exists: boolean }>> {
       const entity = this.entity;
       const options = this.getValidOptions({ where });
 
@@ -517,13 +383,8 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       // add mandatory where
       qb = WhereBuilder.addClause(qb, options.where!).limit(1);
 
-      const { result, ...compiled } = await this.executeQb(qb);
-
-      return {
-         sql: compiled.sql,
-         parameters: [...compiled.parameters],
-         result,
-         exists: result[0]!.count > 0,
-      };
+      return await this.performQuery(qb, {
+         hydrator: (rows) => ({ exists: rows[0]?.count > 0 }),
+      });
    }
 }

app/src/data/entities/query/RepositoryResult.ts

@@ -0,0 +1,105 @@
+import { $console } from "core/console";
+import type { Entity, EntityData } from "../Entity";
+import type { EntityManager } from "../EntityManager";
+import { Result, type ResultJSON, type ResultOptions } from "../Result";
+import type { Compilable, SelectQueryBuilder } from "kysely";
+import { ensureInt } from "core/utils";
+
+export type RepositoryResultOptions = ResultOptions & {
+   silent?: boolean;
+};
+
+export type RepositoryResultJSON<T = EntityData[]> = ResultJSON<T>;
+
+export class RepositoryResult<T = EntityData[]> extends Result<T> {
+   constructor(
+      protected em: EntityManager<any>,
+      public entity: Entity,
+      options?: RepositoryResultOptions,
+   ) {
+      super(em.connection, {
+         hydrator: (rows) => em.hydrate(entity.name, rows as any),
+         beforeExecute: (compiled) => {
+            if (!options?.silent) {
+               $console.debug(`Query:\n${compiled.sql}\n`, compiled.parameters);
+            }
+         },
+         onError: (error) => {
+            if (options?.silent !== true) {
+               $console.error("Repository:", String(error));
+               throw error;
+            }
+         },
+         ...options,
+      });
+   }
+
+   private shouldIncludeCounts(intent?: boolean) {
+      if (intent === undefined) return this.conn.supports("softscans");
+      return intent;
+   }
+
+   override async execute(
+      qb: SelectQueryBuilder<any, any, any>,
+      opts?: { includeCounts?: boolean },
+   ) {
+      const includeCounts = this.shouldIncludeCounts(opts?.includeCounts);
+
+      if (includeCounts) {
+         const selector = (as = "count") => this.conn.kysely.fn.countAll<number>().as(as);
+         const countQuery = qb
+            .clearSelect()
+            .select(selector())
+            .clearLimit()
+            .clearOffset()
+            .clearGroupBy()
+            .clearOrderBy();
+         const totalQuery = this.conn.kysely.selectFrom(this.entity.name).select(selector());
+
+         const compiled = qb.compile();
+         this.options.beforeExecute?.(compiled);
+
+         try {
+            const start = performance.now();
+            const [main, count, total] = await this.em.connection.executeQueries(
+               compiled,
+               countQuery,
+               totalQuery,
+            );
+            this.time = Number.parseFloat((performance.now() - start).toFixed(2));
+            this.results.push({
+               ...main,
+               data: this.options.hydrator?.(main.rows as T[]),
+               items: main.rows.length,
+               count: ensureInt(count.rows[0]?.count ?? 0),
+               total: ensureInt(total.rows[0]?.count ?? 0),
+               time: this.time,
+               sql: compiled.sql,
+               parameters: [...compiled.parameters],
+            });
+         } catch (e) {
+            if (this.options.onError) {
+               await this.options.onError(e as Error);
+            } else {
+               throw e;
+            }
+         }
+
+         return this;
+      }
+
+      return await super.execute(qb);
+   }
+
+   get count() {
+      return this.first().count;
+   }
+
+   get total() {
+      return this.first().total;
+   }
+
+   protected override additionalMetaKeys(): string[] {
+      return ["count", "total"];
+   }
+}

app/src/data/relations/ManyToOneRelation.ts

@@ -208,7 +208,7 @@ export class ManyToOneRelation extends EntityRelation<typeof ManyToOneRelation.s
          [field.targetField()]: primaryReference as any,
       });
 
-      if (!query.exists) {
+      if (!query.data.exists) {
          const idProp = field.targetField();
          throw new Error(
             `Cannot connect "${entity.name}.${key}" to ` +

app/src/data/relations/RelationMutator.ts

@@ -70,7 +70,7 @@ export class RelationMutator {
          [field.targetField()]: value,
       });
 
-      if (!query.exists) {
+      if (!query.data.exists) {
          const idProp = field.targetField();
          throw new Error(
             `Cannot connect "${this.entity.name}.${key}" to ` +