@taylordb/query-builder 0.9.0 → 0.9.2

package/dist/esm/insert-query-builder.js

@@ -1,5 +1,11 @@
 import { QueryBuilder } from './query-builder.js';
 import { SelectionBuilder } from './selection-builder.js';
+/**
+ * A query builder for creating new records in the database.
+ * @template DB - The database type.
+ * @template TableName - The name of the table to insert into.
+ * @template Selection - The type of the selected fields.
+ */
 export class InsertQueryBuilder {
     #node;
     #executor;
@@ -7,12 +13,47 @@ export class InsertQueryBuilder {
         this.#node = node;
         this.#executor = executor;
     }
+    /**
+     * The values to insert into the table.
+     * @param values - An object or array of objects representing the records to create.
+     * @returns The `InsertQueryBuilder` instance for chaining.
+     *
+     * @example Single Record Insertion
+     * ```typescript
+     * const newUser = await qb
+     *   .insertInto('users')
+     *   .values({ name: 'John Doe', email: 'john.doe@example.com' })
+     *   .executeTakeFirst();
+     * ```
+     *
+     * @example Multiple Record Insertion
+     * ```typescript
+     * const newUsers = await qb
+     *   .insertInto('users')
+     *   .values([{ name: 'John Doe' }, { name: 'Jane Doe' }])
+     *   .execute();
+     * ```
+     */
     values(values) {
         return new InsertQueryBuilder({
             ...this.#node,
             createdRecords: Array.isArray(values) ? values : [values],
         }, this.#executor);
     }
+    /**
+     * The fields to return after the insert operation.
+     * @param fields - An array of field names to return.
+     * @returns The `InsertQueryBuilder` instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * const newUser = await qb
+     *   .insertInto('users')
+     *   .values({ name: 'John Doe' })
+     *   .returning(['id', 'name'])
+     *   .executeTakeFirst();
+     * ```
+     */
     returning(fields) {
         const newSelects = fields.map(field => {
             if (typeof field === 'function') {
@@ -28,9 +69,39 @@ export class InsertQueryBuilder {
             returning: [...this.#node.returning, ...newSelects],
         }, this.#executor);
     }
+    /**
+     * Executes the insert query.
+     * @returns A promise that resolves with an array of the selected fields from the inserted records.
+     *
+     * @example
+     * ```typescript
+     * const newUsers = await qb
+     *   .insertInto('users')
+     *   .values([{ name: 'John Doe' }, { name: 'Jane Doe' }])
+     *   .returning(['id', 'name'])
+     *   .execute();
+     * ```
+     */
     async execute() {
         return (await this.#executor.execute(this))[0];
     }
+    /**
+     * Executes the insert query and returns the first result.
+     * @returns A promise that resolves with the first inserted record, or `null` if no records were inserted.
+     *
+     * @example
+     * ```typescript
+     * const newUser = await qb
+     *   .insertInto('users')
+     *   .values({ name: 'John Doe' })
+     *   .returning(['id', 'name'])
+     *   .executeTakeFirst();
+     * ```
+     */
+    async executeTakeFirst() {
+        const response = await this.execute();
+        return response[0] ?? null;
+    }
     compile() {
         const query = 'mutation ($metadata: JSON) { execute(metadata: $metadata) }';
         const metadata = [this._prepareMetadata()];

package/dist/esm/insert-query-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"insert-query-builder.js","sourceRoot":"","sources":["../../src/insert-query-builder.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,OAAO,kBAAkB;IAK7B,KAAK,CAAa;IAClB,SAAS,CAAW;IAEpB,YAAY,IAAgB,EAAE,QAAkB;QAC9C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,MAAM,CACJ,MAA+D;QAE/D,OAAO,IAAI,kBAAkB,CAC3B;YACE,GAAG,IAAI,CAAC,KAAK;YACb,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;SAC1D,EACD,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;IAED,SAAS,CACP,MAAe;QAMf,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE;YACpC,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;gBAChC,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAgB,IAAI,CAAC,SAAS,CAAC,CAAC;gBACpE,aAAa;gBACb,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;gBAChC,OAAO,QAAQ,CAAC,KAAK,CAAC;YACxB,CAAC;YACD,OAAO,KAAe,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,OAAO,IAAI,kBAAkB,CAC3B;YACE,GAAG,IAAI,CAAC,KAAK;YACb,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,UAAU,CAAC;SACpD,EACD,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO;QACX,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,OAAO;QACL,MAAM,KAAK,GAAG,6DAA6D,CAAC;QAE5E,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAE3C,OAAO;YACL,KAAK;YACL,SAAS,EAAE;gBACT,QAAQ;aACT;SACF,CAAC;IACJ,CAAC;IAED,gBAAgB;QACd,MAAM,YAAY,GAAG,CAAC,OAA+B,EAAS,EAAE;YAC9D,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE;gBACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,MAAM,eAAe,GAAG,IAAI,YAAY,CACtC,KAAkB,EAClB,IAAI,CAAC,SAAS,CACf,CAAC;gBACF,OAAO,eAAe,CAAC,gBAAgB,EAAE,CAAC;YAC5C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,MAAM,kBAAkB,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM;YACpD,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;YACpC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAEX,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS;YAC/B,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc;YACzC,SAAS,EAAE,kBAAkB;SAC9B,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"insert-query-builder.js","sourceRoot":"","sources":["../../src/insert-query-builder.ts"],"names":[],"mappings":"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"}

package/dist/esm/query-builder.d.ts

@@ -9,22 +9,166 @@ import { Executor } from './executor.js';
 import { InsertQueryBuilder } from './insert-query-builder.js';
 import { UpdateQueryBuilder } from './update-query-builder.js';
 import { FilterableQueryBuilder } from './where-query-builder.js';
+/**
+ * The main query builder class for constructing and executing select queries.
+ * @template DB - The database type.
+ * @template TableName - The name of the table to query.
+ * @template Selection - The type of the selected fields.
+ * @template LinkName - The name of the link field if this is a subquery.
+ */
 export declare class QueryBuilder<DB extends AnyDB, TableName extends keyof DB, Selection = object, LinkName = null> extends FilterableQueryBuilder<DB, TableName> {
     _node: QueryNode;
     constructor(node: QueryNode, executor: Executor);
+    /**
+     * Selects a set of fields from the table.
+     * @param fields - An array of field names to select.
+     * @returns A new `QueryBuilder` instance with the specified fields selected.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .execute();
+     * ```
+     */
     select<const TFields extends readonly NonLinkColumnNames<DB[TableName]>[]>(fields: TFields): QueryBuilder<DB, TableName, ResolveSelection<DB, TableName, TFields, Selection>>;
+    /**
+     * Selects all fields from the table.
+     * @returns A new `QueryBuilder` instance with all fields selected.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .selectAll()
+     *   .execute();
+     * ```
+     */
     selectAll(): QueryBuilder<DB, TableName, Selection & {
         [K in keyof DB[TableName]]: InferDataType<DB[TableName][K]>;
     }>;
+    /**
+     * Includes related records from a linked table.
+     * This method has two overloads:
+     * 1. Pass an array of link field names to include all fields from the related records.
+     * 2. Pass an object to specify subqueries for each link field.
+     *
+     * @param relations - The relations to include.
+     * @returns A new `QueryBuilder` instance with the specified relations included.
+     *
+     * @example
+     * ```typescript
+     * const usersWithPosts = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .with(['posts']) // Assuming 'posts' is a link field on the 'users' table
+     *   .execute();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const usersWithPublishedPosts = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .with({
+     *     posts: (qb) => qb.select(['title', 'content']).where('isPublished', '=', true),
+     *   })
+     *   .execute();
+     * ```
+     */
     with<const TArg extends (LinkColumnNames<DB[TableName]> & string) | readonly (LinkColumnNames<DB[TableName]> & string)[]>(relations: TArg): QueryBuilder<DB, TableName, ResolveWithPlain<DB, TableName, TArg, Selection>>;
     with<const TArg extends {
         [K in LinkColumnNames<DB[TableName]>]?: (qb: QueryBuilder<DB, DB[TableName][K] extends LinkColumnType<any, boolean> ? DB[TableName][K]['linkedTo'] : never, object, K>) => QueryBuilder<DB, any, any, any>;
     }>(relations: TArg): QueryBuilder<DB, TableName, ResolveWithObject<TArg, Selection>>;
+    /**
+     * Sets the maximum number of records to return.
+     * @param count - The maximum number of records.
+     * @returns A new `QueryBuilder` instance with the limit applied.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .limit(10)
+     *   .execute();
+     * ```
+     */
     limit(count: number): QueryBuilder<DB, TableName, Selection, LinkName>;
+    /**
+     * Sets the number of records to skip.
+     * @param count - The number of records to skip.
+     * @returns A new `QueryBuilder` instance with the offset applied.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .offset(10)
+     *   .execute();
+     * ```
+     */
     offset(count: number): QueryBuilder<DB, TableName, Selection, LinkName>;
+    /**
+     * Paginates the results.
+     * @param page - The page number to retrieve.
+     * @param limit - The number of records per page.
+     * @returns A new `QueryBuilder` instance with pagination applied.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .paginate(2, 25) // Retrieves page 2 with 25 records per page
+     *   .execute();
+     * ```
+     */
     paginate(page: number, limit: number): QueryBuilder<DB, TableName, Selection, LinkName>;
+    /**
+     * 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 `QueryBuilder` instance with the sorting applied.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .orderBy('name', 'asc')
+     *   .execute();
+     * ```
+     */
     orderBy(field: keyof DB[TableName], direction?: 'asc' | 'desc'): QueryBuilder<DB, TableName, Selection, LinkName>;
+    /**
+     * Executes the select query.
+     * @returns A promise that resolves with an array of the selected records.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .execute();
+     * ```
+     */
     execute(): Promise<Selection[]>;
+    /**
+     * Executes the select query and returns the first result.
+     * @returns A promise that resolves with the first record, or `null` if no records were found.
+     *
+     * @example
+     * ```typescript
+     * const user = await qb
+     *   .selectFrom('users')
+     *   .where('id', '=', 1)
+     *   .select(['id', 'name'])
+     *   .executeTakeFirst();
+     * ```
+     */
     executeTakeFirst(): Promise<Selection | null>;
     subscribe(callback: (result: Selection[]) => void): Promise<{
         unsubscribe: () => Promise<void>;
@@ -37,19 +181,94 @@ export declare class QueryBuilder<DB extends AnyDB, TableName extends keyof DB,
     isSelectionQueryNode(node: QueryNode): node is SelectionQueryNode;
     isRootQueryNode(node: QueryNode): node is RootQueryNode;
 }
-export declare class RootQueryBuilder<DB extends AnyDB> {
+/**
+ * The root query builder class that provides entry points for all query types.
+ */
+export declare class BaseRootQueryBuilder<DB extends AnyDB> {
     #private;
-    constructor(config: {
-        baseUrl: string;
-        apiKey: string;
-    });
+    constructor(executor: Executor);
+    /**
+     * Creates a new select query builder for the specified table.
+     * @param from - The name of the table to select from.
+     * @returns A new `QueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const userQuery = qb.selectFrom('users');
+     * ```
+     */
     selectFrom<TableName extends keyof Omit<DB, 'selectTable' | 'attachmentTable' | 'collaboratorsTable'> & string>(from: TableName): QueryBuilder<DB, TableName>;
+    /**
+     * Creates a new insert query builder for the specified table.
+     * @param into - The name of the table to insert into.
+     * @returns A new `InsertQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const insertQuery = qb.insertInto('users');
+     * ```
+     */
     insertInto<TableName extends keyof Omit<DB, 'selectTable' | 'attachmentTable' | 'collaboratorsTable'> & string>(into: TableName): InsertQueryBuilder<DB, TableName>;
+    /**
+     * Creates a new update query builder for the specified table.
+     * @param tableName - The name of the table to update.
+     * @returns A new `UpdateQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const updateQuery = qb.update('users');
+     * ```
+     */
     update<TableName extends keyof Omit<DB, 'selectTable' | 'attachmentTable' | 'collaboratorsTable'> & string>(tableName: TableName): UpdateQueryBuilder<DB, TableName>;
+    /**
+     * Creates a new delete query builder for the specified table.
+     * @param tableName - The name of the table to delete from.
+     * @returns A new `DeleteQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const deleteQuery = qb.deleteFrom('users');
+     * ```
+     */
     deleteFrom<TableName extends keyof Omit<DB, 'selectTable' | 'attachmentTable' | 'collaboratorsTable'> & string>(tableName: TableName): DeleteQueryBuilder<DB, TableName>;
+    /**
+     * Creates a new batch query builder.
+     * @param builders - An array of query builders to execute in a batch.
+     * @returns A new `BatchQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const batchQuery = qb.batch([
+     *   qb.selectFrom('users').select(['id', 'name']),
+     *   qb.insertInto('users').values({ name: 'New User' }),
+     * ]);
+     * const [users, newUser] = await batchQuery.execute();
+     * ```
+     */
     batch<const TBuilders extends readonly AnyQueryBuilder[]>(builders: TBuilders): AreAllBuildersSubscribable<TBuilders> extends true ? BatchQueryBuilder<TBuilders> : Omit<BatchQueryBuilder<TBuilders>, 'subscribe'>;
+    /**
+     * Creates a new aggregation query builder for the specified table.
+     * @param tableName - The name of the table to aggregate from.
+     * @returns A new `AggregationQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const aggregateQuery = qb.aggregateFrom('users');
+     * ```
+     */
     aggregateFrom<TableName extends keyof Omit<DB, 'selectTable' | 'attachmentTable' | 'collaboratorsTable'> & string>(tableName: TableName): AggregationQueryBuilder<DB, TableName>;
 }
+export declare class RootQueryBuilder<DB extends AnyDB> extends BaseRootQueryBuilder<DB> {
+    #private;
+    constructor(executor: Executor);
+    transaction<T>(callback: (qb: BaseRootQueryBuilder<DB>) => Promise<T>): Promise<T>;
+}
 export declare function createQueryBuilder<DB extends AnyDB>(config: {
     baseUrl: string;
     apiKey: string;

package/dist/esm/query-builder.js

@@ -8,6 +8,13 @@ import { SelectionBuilder } from './selection-builder.js';
 import { UpdateQueryBuilder } from './update-query-builder.js';
 import { FilterableQueryBuilder } from './where-query-builder.js';
 const DEFAULT_LIMIT = 50;
+/**
+ * The main query builder class for constructing and executing select queries.
+ * @template DB - The database type.
+ * @template TableName - The name of the table to query.
+ * @template Selection - The type of the selected fields.
+ * @template LinkName - The name of the link field if this is a subquery.
+ */
 export class QueryBuilder extends FilterableQueryBuilder {
     constructor(node, executor) {
         super(node, executor);
@@ -16,12 +23,37 @@ export class QueryBuilder extends FilterableQueryBuilder {
             pagination: { limit: DEFAULT_LIMIT, offset: 0, ...node.pagination },
         };
     }
+    /**
+     * Selects a set of fields from the table.
+     * @param fields - An array of field names to select.
+     * @returns A new `QueryBuilder` instance with the specified fields selected.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .execute();
+     * ```
+     */
     select(fields) {
         return new QueryBuilder({
             ...this._node,
             fields: [...this._node.fields, ...fields],
         }, this._executor);
     }
+    /**
+     * Selects all fields from the table.
+     * @returns A new `QueryBuilder` instance with all fields selected.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .selectAll()
+     *   .execute();
+     * ```
+     */
     selectAll() {
         return new QueryBuilder({
             ...this._node,
@@ -55,21 +87,79 @@ export class QueryBuilder extends FilterableQueryBuilder {
             fields: [...this._node.fields, ...newSelects],
         }, this._executor);
     }
+    /**
+     * Sets the maximum number of records to return.
+     * @param count - The maximum number of records.
+     * @returns A new `QueryBuilder` instance with the limit applied.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .limit(10)
+     *   .execute();
+     * ```
+     */
     limit(count) {
         return new QueryBuilder({
             ...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 `QueryBuilder` instance with the offset applied.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .offset(10)
+     *   .execute();
+     * ```
+     */
     offset(count) {
         return new QueryBuilder({
             ...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 `QueryBuilder` instance with pagination applied.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .paginate(2, 25) // Retrieves page 2 with 25 records per page
+     *   .execute();
+     * ```
+     */
     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 `QueryBuilder` instance with the sorting applied.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .orderBy('name', 'asc')
+     *   .execute();
+     * ```
+     */
     orderBy(field, direction = 'asc') {
         const newSorting = {
             field: field,
@@ -80,10 +170,35 @@ export class QueryBuilder extends FilterableQueryBuilder {
             sorting: [...(this._node.sorting || []), newSorting],
         }, this._executor);
     }
+    /**
+     * Executes the select query.
+     * @returns A promise that resolves with an array of the selected records.
+     *
+     * @example
+     * ```typescript
+     * const users = await qb
+     *   .selectFrom('users')
+     *   .select(['id', 'name'])
+     *   .execute();
+     * ```
+     */
     async execute() {
         const response = await this._executor.execute(this);
         return response[0];
     }
+    /**
+     * Executes the select query and returns the first result.
+     * @returns A promise that resolves with the first record, or `null` if no records were found.
+     *
+     * @example
+     * ```typescript
+     * const user = await qb
+     *   .selectFrom('users')
+     *   .where('id', '=', 1)
+     *   .select(['id', 'name'])
+     *   .executeTakeFirst();
+     * ```
+     */
     async executeTakeFirst() {
         const response = await this._executor.execute(this);
         return response[0]?.[0] ?? null;
@@ -144,11 +259,25 @@ export class QueryBuilder extends FilterableQueryBuilder {
         return node.queryType === 'root';
     }
 }
-export class RootQueryBuilder {
+/**
+ * The root query builder class that provides entry points for all query types.
+ */
+export class BaseRootQueryBuilder {
     #executor;
-    constructor(config) {
-        this.#executor = new Executor(config.baseUrl, config.apiKey);
+    constructor(executor) {
+        this.#executor = executor;
     }
+    /**
+     * Creates a new select query builder for the specified table.
+     * @param from - The name of the table to select from.
+     * @returns A new `QueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const userQuery = qb.selectFrom('users');
+     * ```
+     */
     selectFrom(from) {
         return new QueryBuilder({
             tableName: from,
@@ -158,6 +287,17 @@ export class RootQueryBuilder {
             queryType: 'root',
         }, this.#executor);
     }
+    /**
+     * Creates a new insert query builder for the specified table.
+     * @param into - The name of the table to insert into.
+     * @returns A new `InsertQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const insertQuery = qb.insertInto('users');
+     * ```
+     */
     insertInto(into) {
         return new InsertQueryBuilder({
             tableName: into,
@@ -166,6 +306,17 @@ export class RootQueryBuilder {
             type: 'create',
         }, this.#executor);
     }
+    /**
+     * Creates a new update query builder for the specified table.
+     * @param tableName - The name of the table to update.
+     * @returns A new `UpdateQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const updateQuery = qb.update('users');
+     * ```
+     */
     update(tableName) {
         return new UpdateQueryBuilder({
             tableName: tableName,
@@ -174,6 +325,17 @@ export class RootQueryBuilder {
             type: 'update',
         }, this.#executor);
     }
+    /**
+     * Creates a new delete query builder for the specified table.
+     * @param tableName - The name of the table to delete from.
+     * @returns A new `DeleteQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const deleteQuery = qb.deleteFrom('users');
+     * ```
+     */
     deleteFrom(tableName) {
         return new DeleteQueryBuilder({
             tableName: tableName,
@@ -182,9 +344,35 @@ export class RootQueryBuilder {
             type: 'delete',
         }, this.#executor);
     }
+    /**
+     * Creates a new batch query builder.
+     * @param builders - An array of query builders to execute in a batch.
+     * @returns A new `BatchQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const batchQuery = qb.batch([
+     *   qb.selectFrom('users').select(['id', 'name']),
+     *   qb.insertInto('users').values({ name: 'New User' }),
+     * ]);
+     * const [users, newUser] = await batchQuery.execute();
+     * ```
+     */
     batch(builders) {
         return new BatchQueryBuilder(builders, this.#executor);
     }
+    /**
+     * Creates a new aggregation query builder for the specified table.
+     * @param tableName - The name of the table to aggregate from.
+     * @returns A new `AggregationQueryBuilder` instance.
+     *
+     * @example
+     * ```typescript
+     * const qb = createQueryBuilder<MyDatabase>({ ... });
+     * const aggregateQuery = qb.aggregateFrom('users');
+     * ```
+     */
     aggregateFrom(tableName) {
         const node = {
             tableName: tableName,
@@ -196,12 +384,37 @@ export class RootQueryBuilder {
         return new AggregationQueryBuilder(node, this.#executor);
     }
 }
+export class RootQueryBuilder extends BaseRootQueryBuilder {
+    #executor;
+    constructor(executor) {
+        super(executor);
+        this.#executor = executor;
+    }
+    async transaction(callback) {
+        if (this.#executor.isInTransaction) {
+            throw new Error('Nested transactions are not supported.');
+        }
+        const { startTransaction: transactionId } = await this.#executor.rawRequest('mutation { startTransaction }', {});
+        const transactionalExecutor = this.#executor.withTransactionId(transactionId);
+        const transactionalQb = new BaseRootQueryBuilder(transactionalExecutor);
+        try {
+            const result = await callback(transactionalQb);
+            await transactionalExecutor.rawRequest('mutation { commitTransaction }', {});
+            return result;
+        }
+        catch (error) {
+            await transactionalExecutor.rawRequest('mutation { rollbackTransaction }', {});
+            throw error;
+        }
+    }
+}
 const QBConfigSchema = z.object({
     baseUrl: z.string().url(),
     apiKey: z.string().nonempty(),
 });
 export function createQueryBuilder(config) {
     QBConfigSchema.parse(config);
-    return new RootQueryBuilder(config);
+    const executor = new Executor(config.baseUrl, config.apiKey);
+    return new RootQueryBuilder(executor);
 }
 //# sourceMappingURL=query-builder.js.map