@taylordb/query-builder 0.9.0 → 0.9.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TaylorDB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -111,3 +111,45 @@ const aggregates = await qb
   })
   .execute();
 ```
+
+## Recipes
+
+### Select with Relations
+
+You can use the `with` method to fetch related records from a linked table.
+
+```typescript
+// Assuming 'customers' has a link field 'orders' to the 'orders' table
+const customersWithOrders = await qb
+  .selectFrom('customers')
+  .select(['firstName', 'lastName'])
+  .with({
+    orders: qb => qb.select(['orderDate', 'total']),
+  })
+  .execute();
+```
+
+### Cross-Filters
+
+You can filter records in one table based on the values in a linked table.
+
+```typescript
+// Get all customers who have placed an order with a total greater than 100
+const highValueCustomers = await qb
+  .selectFrom('customers')
+  .where('orders', 'hasAnyOf', qb => qb.where('total', '>', 100))
+  .execute();
+```
+
+### Conditional Updates
+
+You can use `where` clauses to update only the records that match a specific condition.
+
+```typescript
+// Update the status of all orders placed before a certain date
+const { affectedRecords } = await qb
+  .update('orders')
+  .set({ status: 'archived' })
+  .where('orderDate', '<', '2023-01-01')
+  .execute();
+```

package/dist/cjs/__tests__/query-builder.spec.js

@@ -1,20 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_js_1 = require("../index.js");
+const socket_connection_js_1 = require("../socket-connection.js");
+jest.mock('socket.io-client', () => {
+    const mockSocket = {
+        on: jest.fn(),
+        emit: jest.fn(),
+        once: jest.fn(),
+    };
+    return {
+        io: jest.fn(() => mockSocket),
+    };
+});
 describe('QueryBuilder', () => {
+    let mockRawRequest;
+    beforeEach(() => {
+        mockRawRequest = jest.fn().mockResolvedValue({ execute: [] });
+        socket_connection_js_1.SocketConnection.prototype.rawRequest = mockRawRequest;
+    });
     // @ts-ignore
     const qb = (0, index_js_1.createQueryBuilder)({
         baseUrl: 'http://localhost',
         apiKey: 'test',
     });
-    it('should compile a select query', () => {
-        const { variables } = qb
+    it('should compile a select query and execute', async () => {
+        await qb
             .selectFrom('customers')
             .select(['firstName', 'lastName'])
             .where('firstName', '=', 'John')
             .orderBy('lastName', 'asc')
             .paginate(1, 10)
-            .compile();
+            .execute();
+        expect(mockRawRequest).toHaveBeenCalledTimes(1);
+        const variables = mockRawRequest.mock.calls[0][1];
         expect(variables.metadata[0]).toMatchObject({
             type: 'select',
             tableName: 'customers',
@@ -33,26 +51,30 @@ describe('QueryBuilder', () => {
             pagination: { offset: 0, limit: 10 },
         });
     });
-    it('should compile an insert query', () => {
-        const { variables } = qb
+    it('should compile an insert query and execute', async () => {
+        await qb
             .insertInto('customers')
             .values({
             firstName: 'Jane',
             lastName: 'Doe',
         })
-            .compile();
+            .execute();
+        expect(mockRawRequest).toHaveBeenCalledTimes(1);
+        const variables = mockRawRequest.mock.calls[0][1];
         expect(variables.metadata[0]).toMatchObject({
             type: 'create',
             tableName: 'customers',
             createdRecords: [{ firstName: 'Jane', lastName: 'Doe' }],
         });
     });
-    it('should compile an update query', () => {
-        const { variables } = qb
+    it('should compile an update query and execute', async () => {
+        await qb
             .update('customers')
             .set({ lastName: 'Smith' })
             .where('id', '=', 1)
-            .compile();
+            .execute();
+        expect(mockRawRequest).toHaveBeenCalledTimes(1);
+        const variables = mockRawRequest.mock.calls[0][1];
         expect(variables.metadata[0]).toMatchObject({
             type: 'update',
             tableName: 'customers',
@@ -69,11 +91,10 @@ describe('QueryBuilder', () => {
             },
         });
     });
-    it('should compile a delete query', () => {
-        const { variables } = qb
-            .deleteFrom('customers')
-            .where('id', '=', 1)
-            .compile();
+    it('should compile a delete query and execute', async () => {
+        await qb.deleteFrom('customers').where('id', '=', 1).execute();
+        expect(mockRawRequest).toHaveBeenCalledTimes(1);
+        const variables = mockRawRequest.mock.calls[0][1];
         expect(variables.metadata[0]).toMatchObject({
             type: 'delete',
             tableName: 'customers',
@@ -89,15 +110,17 @@ describe('QueryBuilder', () => {
             },
         });
     });
-    it('should compile a batch query', async () => {
-        const { variables } = qb
+    it('should compile a batch query and execute', async () => {
+        await qb
             .batch([
             qb.selectFrom('customers').select(['firstName', 'lastName']),
             qb
                 .insertInto('customers')
                 .values({ firstName: 'John', lastName: 'Doe' }),
         ])
-            .compile();
+            .execute();
+        expect(mockRawRequest).toHaveBeenCalledTimes(1);
+        const variables = mockRawRequest.mock.calls[0][1];
         expect(variables.metadata).toHaveLength(2);
         expect(variables.metadata[0]).toMatchObject({
             type: 'select',
@@ -108,14 +131,16 @@ describe('QueryBuilder', () => {
             tableName: 'customers',
         });
     });
-    it('should compile an aggregate query', () => {
-        const { variables } = qb
+    it('should compile an aggregate query and execute', async () => {
+        await qb
             .aggregateFrom('customers')
             .groupBy('firstName', 'asc')
             .withAggregates({
             id: ['sum'],
         })
-            .compile();
+            .execute();
+        expect(mockRawRequest).toHaveBeenCalledTimes(1);
+        const variables = mockRawRequest.mock.calls[0][1];
         expect(variables.metadata[0]).toMatchObject({
             type: 'aggregation',
             tableName: 'customers',
@@ -125,11 +150,13 @@ describe('QueryBuilder', () => {
             },
         });
     });
-    it('should compile a cross-table query', () => {
-        const { variables } = qb
+    it('should compile a cross-table query and execute', async () => {
+        await qb
             .selectFrom('customers')
             .where('orders', 'hasAnyOf', qb => qb.where('amount', '>', 100))
-            .compile();
+            .execute();
+        expect(mockRawRequest).toHaveBeenCalledTimes(1);
+        const variables = mockRawRequest.mock.calls[0][1];
         expect(variables.metadata[0]).toMatchObject({
             type: 'select',
             tableName: 'customers',
@@ -157,5 +184,81 @@ describe('QueryBuilder', () => {
             },
         });
     });
+    it('should handle a successful transaction', async () => {
+        const mockRawRequest = jest
+            .fn()
+            .mockResolvedValueOnce({
+            startTransaction: 'test-transaction-id',
+        })
+            .mockResolvedValueOnce({ execute: [] })
+            .mockResolvedValueOnce({ commitTransaction: true });
+        socket_connection_js_1.SocketConnection.prototype.rawRequest = mockRawRequest;
+        // @ts-ignore
+        const qb = (0, index_js_1.createQueryBuilder)({
+            baseUrl: 'http://localhost',
+            apiKey: 'test',
+        });
+        await qb.transaction(txQb => {
+            return txQb
+                .insertInto('customers')
+                .values({ firstName: 'John', lastName: 'Doe' })
+                .execute();
+        });
+        expect(mockRawRequest).toHaveBeenCalledTimes(3);
+        const startTransactionCall = mockRawRequest.mock.calls[0];
+        expect(startTransactionCall[0]).toContain('startTransaction');
+        const executeCall = mockRawRequest.mock.calls[1];
+        expect(executeCall[3]).toBe('test-transaction-id');
+        const commitTransactionCall = mockRawRequest.mock.calls[2];
+        expect(commitTransactionCall[0]).toContain('commitTransaction');
+        expect(commitTransactionCall[3]).toBe('test-transaction-id');
+    });
+    it('should handle a failed transaction and rollback', async () => {
+        const transactionId = 'test-transaction-id-fail';
+        const errorMessage = 'Something went wrong';
+        const mockRawRequest = jest
+            .fn()
+            .mockResolvedValueOnce({ startTransaction: transactionId })
+            .mockRejectedValueOnce(new Error(errorMessage))
+            .mockResolvedValueOnce({ rollbackTransaction: true });
+        socket_connection_js_1.SocketConnection.prototype.rawRequest = mockRawRequest;
+        // @ts-ignore
+        const qb = (0, index_js_1.createQueryBuilder)({
+            baseUrl: 'http://localhost',
+            apiKey: 'test',
+        });
+        await expect(qb.transaction(txQb => {
+            return txQb
+                .insertInto('customers')
+                .values({ firstName: 'John', lastName: 'Doe' })
+                .execute();
+        })).rejects.toThrow(errorMessage);
+        expect(mockRawRequest).toHaveBeenCalledTimes(3);
+        const startTransactionCall = mockRawRequest.mock.calls[0];
+        expect(startTransactionCall[0]).toContain('startTransaction');
+        const executeCall = mockRawRequest.mock.calls[1];
+        expect(executeCall[3]).toBe(transactionId);
+        const rollbackTransactionCall = mockRawRequest.mock.calls[2];
+        expect(rollbackTransactionCall[0]).toContain('rollbackTransaction');
+        expect(rollbackTransactionCall[3]).toBe(transactionId);
+    });
+    it('should not have transaction method within a transaction', async () => {
+        const mockRawRequest = jest
+            .fn()
+            .mockResolvedValueOnce({
+            startTransaction: 'test-transaction-id-no-nested',
+        })
+            .mockResolvedValueOnce({ commitTransaction: true });
+        socket_connection_js_1.SocketConnection.prototype.rawRequest = mockRawRequest;
+        // @ts-ignore
+        const qb = (0, index_js_1.createQueryBuilder)({
+            baseUrl: 'http://localhost',
+            apiKey: 'test',
+        });
+        await qb.transaction(async (txQb) => {
+            expect(txQb).not.toHaveProperty('transaction');
+        });
+        expect(mockRawRequest).toHaveBeenCalledTimes(2);
+    });
 });
 //# sourceMappingURL=query-builder.spec.js.map

package/dist/cjs/__tests__/query-builder.spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-builder.spec.js","sourceRoot":"","sources":["../../../src/__tests__/query-builder.spec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query-builder.spec.js","sourceRoot":"","sources":["../../../src/__tests__/query-builder.spec.ts"],"names":[],"mappings":"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"}

package/dist/cjs/aggregation-query-builder.d.ts

@@ -2,23 +2,115 @@ import type { AggregateNode, AggregateRecord } from './@types/aggregate.js';
 import type { AnyDB } from './@types/internal-types.js';
 import { Executor } from './executor.js';
 import { FilterableQueryBuilder } from './where-query-builder.js';
+/**
+ * A query builder for performing aggregation queries.
+ * @template DB - The database type.
+ * @template TableName - The name of the table to aggregate from.
+ * @template TGroupBy - The fields to group by.
+ * @template TAggregations - The aggregations to perform.
+ */
 export declare class AggregationQueryBuilder<DB extends AnyDB, TableName extends keyof DB, TGroupBy extends readonly (keyof DB[TableName] & string)[] = [], TAggregations extends {
     [K in keyof DB[TableName] & string]?: readonly (keyof DB[TableName][K]['aggregations'])[];
 } = object> extends FilterableQueryBuilder<DB, TableName> {
     #private;
     constructor(node: AggregateNode, executor: Executor);
+    /**
+     * Groups the results by a specified field.
+     * @param field - The field to group by.
+     * @param direction - The sort direction for the grouping.
+     * @returns A new `AggregationQueryBuilder` instance with the grouping applied.
+     *
+     * @example
+     * ```typescript
+     * const userCounts = await qb
+     *   .aggregateFrom('users')
+     *   .groupBy('role')
+     *   .withAggregates({ id: ['count'] })
+     *   .execute();
+     * ```
+     */
     groupBy<const TField extends keyof DB[TableName] & string>(field: TField, direction?: 'asc' | 'desc'): AggregationQueryBuilder<DB, TableName, [
         ...TGroupBy,
         TField
     ], TAggregations>;
+    /**
+     * Specifies the aggregations to perform.
+     * @param aggregates - An object where the keys are field names and the values are arrays of aggregation functions.
+     * @returns A new `AggregationQueryBuilder` instance with the aggregations applied.
+     *
+     * @example
+     * ```typescript
+     * const userStats = await qb
+     *   .aggregateFrom('users')
+     *   .withAggregates({
+     *     id: ['count'],
+     *     age: ['avg', 'sum'],
+     *   })
+     *   .execute();
+     * ```
+     */
     withAggregates<const T extends {
         [K in keyof DB[TableName] & string]?: readonly (keyof DB[TableName][K]['aggregations'])[];
     }>(aggregates: T): AggregationQueryBuilder<DB, TableName, TGroupBy, TAggregations & T>;
+    /**
+     * Sets the maximum number of records to return.
+     * @param count - The maximum number of records.
+     * @returns A new `AggregationQueryBuilder` instance with the limit applied.
+     */
     limit(count: number): AggregationQueryBuilder<DB, TableName, TGroupBy, TAggregations>;
+    /**
+     * Sets the number of records to skip.
+     * @param count - The number of records to skip.
+     * @returns A new `AggregationQueryBuilder` instance with the offset applied.
+     */
     offset(count: number): AggregationQueryBuilder<DB, TableName, TGroupBy, TAggregations>;
+    /**
+     * Paginates the results.
+     * @param page - The page number to retrieve.
+     * @param limit - The number of records per page.
+     * @returns A new `AggregationQueryBuilder` instance with pagination applied.
+     */
     paginate(page: number, limit: number): AggregationQueryBuilder<DB, TableName, TGroupBy, TAggregations>;
+    /**
+     * Sorts the results by a specified field.
+     * @param field - The field to sort by.
+     * @param direction - The sort direction ('asc' or 'desc').
+     * @returns A new `AggregationQueryBuilder` instance with the sorting applied.
+     */
     orderBy(field: keyof DB[TableName], direction?: 'asc' | 'desc'): AggregationQueryBuilder<DB, TableName, TGroupBy, TAggregations>;
+    /**
+     * Executes the aggregation query.
+     * @returns A promise that resolves with an array of the aggregation results.
+     *
+     * @example
+     * ```typescript
+     * const userCounts = await qb
+     *   .aggregateFrom('users')
+     *   .groupBy('role')
+     *   .withAggregates({ id: ['count'] })
+     *   .execute();
+     * ```
+     */
     execute(): Promise<AggregateRecord<DB, TableName, TGroupBy, TAggregations>[]>;
+    /**
+     * Subscribes to the results of the aggregation query.
+     * @param callback - A callback function that will be called with the results of the aggregation query.
+     * @returns A function to unsubscribe from the query.
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = qb
+     *   .aggregateFrom('users')
+     *   .groupBy('role')
+     *   .withAggregates({ id: ['count'] })
+     *   .subscribe((userCounts) => {
+     *     console.log('User counts by role:', userCounts);
+     *   });
+     *
+     * // To stop listening for updates
+     * unsubscribe();
+     * ```
+     */
     subscribe(callback: (result: AggregateRecord<DB, TableName, TGroupBy, TAggregations>[]) => void): Promise<{
         unsubscribe: () => Promise<void>;
     }>;

package/dist/cjs/aggregation-query-builder.js

@@ -2,12 +2,34 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AggregationQueryBuilder = void 0;
 const where_query_builder_js_1 = require("./where-query-builder.js");
+/**
+ * A query builder for performing aggregation queries.
+ * @template DB - The database type.
+ * @template TableName - The name of the table to aggregate from.
+ * @template TGroupBy - The fields to group by.
+ * @template TAggregations - The aggregations to perform.
+ */
 class AggregationQueryBuilder extends where_query_builder_js_1.FilterableQueryBuilder {
     #node;
     constructor(node, executor) {
         super(node, executor);
         this.#node = node;
     }
+    /**
+     * Groups the results by a specified field.
+     * @param field - The field to group by.
+     * @param direction - The sort direction for the grouping.
+     * @returns A new `AggregationQueryBuilder` instance with the grouping applied.
+     *
+     * @example
+     * ```typescript
+     * const userCounts = await qb
+     *   .aggregateFrom('users')
+     *   .groupBy('role')
+     *   .withAggregates({ id: ['count'] })
+     *   .execute();
+     * ```
+     */
     groupBy(field, direction = 'asc') {
         const newGrouping = {
             field,
@@ -18,6 +40,22 @@ class AggregationQueryBuilder extends where_query_builder_js_1.FilterableQueryBu
             groupings: [...(this.#node.groupings || []), newGrouping],
         }, this._executor);
     }
+    /**
+     * Specifies the aggregations to perform.
+     * @param aggregates - An object where the keys are field names and the values are arrays of aggregation functions.
+     * @returns A new `AggregationQueryBuilder` instance with the aggregations applied.
+     *
+     * @example
+     * ```typescript
+     * const userStats = await qb
+     *   .aggregateFrom('users')
+     *   .withAggregates({
+     *     id: ['count'],
+     *     age: ['avg', 'sum'],
+     *   })
+     *   .execute();
+     * ```
+     */
     withAggregates(aggregates) {
         const newAggregates = { ...this.#node.aggregations };
         for (const key in aggregates) {
@@ -28,21 +66,43 @@ class AggregationQueryBuilder extends where_query_builder_js_1.FilterableQueryBu
             aggregations: newAggregates,
         }, this._executor);
     }
+    /**
+     * Sets the maximum number of records to return.
+     * @param count - The maximum number of records.
+     * @returns A new `AggregationQueryBuilder` instance with the limit applied.
+     */
     limit(count) {
         return new AggregationQueryBuilder({
             ...this.#node,
             pagination: { ...this.#node.pagination, limit: count },
         }, this._executor);
     }
+    /**
+     * Sets the number of records to skip.
+     * @param count - The number of records to skip.
+     * @returns A new `AggregationQueryBuilder` instance with the offset applied.
+     */
     offset(count) {
         return new AggregationQueryBuilder({
             ...this.#node,
             pagination: { ...this.#node.pagination, offset: count },
         }, this._executor);
     }
+    /**
+     * Paginates the results.
+     * @param page - The page number to retrieve.
+     * @param limit - The number of records per page.
+     * @returns A new `AggregationQueryBuilder` instance with pagination applied.
+     */
     paginate(page, limit) {
         return this.offset((page - 1) * limit).limit(limit);
     }
+    /**
+     * Sorts the results by a specified field.
+     * @param field - The field to sort by.
+     * @param direction - The sort direction ('asc' or 'desc').
+     * @returns A new `AggregationQueryBuilder` instance with the sorting applied.
+     */
     orderBy(field, direction = 'asc') {
         const newSorting = {
             field: field,
@@ -53,10 +113,42 @@ class AggregationQueryBuilder extends where_query_builder_js_1.FilterableQueryBu
             sorting: [...(this.#node.sorting || []), newSorting],
         }, this._executor);
     }
+    /**
+     * Executes the aggregation query.
+     * @returns A promise that resolves with an array of the aggregation results.
+     *
+     * @example
+     * ```typescript
+     * const userCounts = await qb
+     *   .aggregateFrom('users')
+     *   .groupBy('role')
+     *   .withAggregates({ id: ['count'] })
+     *   .execute();
+     * ```
+     */
     async execute() {
         const response = await this._executor.execute(this);
         return response;
     }
+    /**
+     * Subscribes to the results of the aggregation query.
+     * @param callback - A callback function that will be called with the results of the aggregation query.
+     * @returns A function to unsubscribe from the query.
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = qb
+     *   .aggregateFrom('users')
+     *   .groupBy('role')
+     *   .withAggregates({ id: ['count'] })
+     *   .subscribe((userCounts) => {
+     *     console.log('User counts by role:', userCounts);
+     *   });
+     *
+     * // To stop listening for updates
+     * unsubscribe();
+     * ```
+     */
     subscribe(callback) {
         return this._executor.subscribe([this], callback);
     }

package/dist/cjs/aggregation-query-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"aggregation-query-builder.js","sourceRoot":"","sources":["../../src/aggregation-query-builder.ts"],"names":[],"mappings":";;;AAOA,qEAAkE;AAElE,MAAa,uBAQX,SAAQ,+CAAqC;IAC7C,KAAK,CAAgB;IAErB,YAAY,IAAmB,EAAE,QAAkB;QACjD,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,OAAO,CACL,KAAa,EACb,YAA4B,KAAK;QAOjC,MAAM,WAAW,GAAkC;YACjD,KAAK;YACL,SAAS;SACV,CAAC;QAEF,OAAO,IAAI,uBAAuB,CAChC;YACE,GAAG,IAAI,CAAC,KAAK;YACb,SAAS,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,WAAW,CAAC;SAC1D,EACD,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;IAED,cAAc,CAMZ,UAAa;QAEb,MAAM,aAAa,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;QACrD,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,aAAa,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAE,CAAC,GAAG,CACvC,SAAS,CAAC,EAAE,CAAC,SAAmB,CACjC,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,uBAAuB,CAChC;YACE,GAAG,IAAI,CAAC,KAAK;YACb,YAAY,EAAE,aAAa;SAC5B,EACD,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;IAED,KAAK,CACH,KAAa;QAEb,OAAO,IAAI,uBAAuB,CAChC;YACE,GAAG,IAAI,CAAC,KAAK;YACb,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE;SACvD,EACD,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;IAED,MAAM,CACJ,KAAa;QAEb,OAAO,IAAI,uBAAuB,CAChC;YACE,GAAG,IAAI,CAAC,KAAK;YACb,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE;SACxD,EACD,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;IAED,QAAQ,CACN,IAAY,EACZ,KAAa;QAEb,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,CACL,KAA0B,EAC1B,YAA4B,KAAK;QAEjC,MAAM,UAAU,GAA+B;YAC7C,KAAK,EAAE,KAAe;YACtB,SAAS;SACV,CAAC;QAEF,OAAO,IAAI,uBAAuB,CAChC;YACE,GAAG,IAAI,CAAC,KAAK;YACb,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC;SACrD,EACD,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO;QAGX,MAAM,QAAQ,GACZ,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAE1B,IAAI,CAAC,CAAC;QACV,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,SAAS,CACP,QAES;QAET,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;IACpD,CAAC;IAED,OAAO;QACL,MAAM,KAAK,GAAG,6DAA6D,CAAC;QAC5E,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAC3C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC;IAC5C,CAAC;IAED,gBAAgB;QACd,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS;YAC/B,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS;YAC/B,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY;YACrC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;gBAC7C,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE;gBACvC,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/D,CAAC;IACJ,CAAC;CACF;AArJD,0DAqJC"}
+{"version":3,"file":"aggregation-query-builder.js","sourceRoot":"","sources":["../../src/aggregation-query-builder.ts"],"names":[],"mappings":"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"}

package/dist/cjs/batch-query-builder.d.ts

@@ -10,12 +10,48 @@ type InferExecuteResult<TBuilder> = TBuilder extends {
     execute: () => Promise<any>;
 } ? Awaited<ReturnType<TBuilder['execute']>> : never;
 export type AreAllBuildersSubscribable<TBuilders extends readonly AnyQueryBuilder[]> = TBuilders[number] extends AnySubscribableQueryBuilder ? true : false;
+/**
+ * A query builder for executing multiple queries in a single batch.
+ * @template TBuilders - An array of query builders to execute.
+ */
 export declare class BatchQueryBuilder<const TBuilders extends readonly AnyQueryBuilder[]> {
     #private;
     constructor(builders: TBuilders, executor: Executor);
+    /**
+     * Executes the batch query.
+     * @returns A promise that resolves with an array of the results from each query in the batch.
+     *
+     * @example
+     * ```typescript
+     * const [users, newUser] = await qb.batch([
+     *   qb.selectFrom('users').select(['id', 'name']),
+     *   qb.insertInto('users').values({ name: 'New User' }).returning(['id', 'name']),
+     * ]).execute();
+     * ```
+     */
     execute(): Promise<{
         -readonly [K in keyof TBuilders]: InferExecuteResult<TBuilders[K]>;
     }>;
+    /**
+     * Subscribes to the results of the batch query.
+     * This is only possible if all queries in the batch are subscribable (select and aggregate).
+     * @param callback - A callback function that will be called with the results of the batch query.
+     * @returns A function to unsubscribe from the query.
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = qb.batch([
+     *   qb.selectFrom('users').select(['id', 'name']),
+     *   qb.aggregateFrom('users').groupBy('role').withAggregates({ id: ['count'] }),
+     * ]).subscribe(([users, userAggregates]) => {
+     *   console.log('Users:', users);
+     *   console.log('User Aggregates:', userAggregates);
+     * });
+     *
+     * // To stop listening for updates
+     * unsubscribe();
+     * ```
+     */
     subscribe(callback: (...results: {
         -readonly [K in keyof TBuilders]: InferExecuteResult<TBuilders[K]>;
     }) => void): Promise<{