@taylordb/query-builder 0.9.0 → 0.9.2

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

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BatchQueryBuilder = void 0;
 const aggregation_query_builder_js_1 = require("./aggregation-query-builder.js");
 const query_builder_js_1 = require("./query-builder.js");
+/**
+ * A query builder for executing multiple queries in a single batch.
+ * @template TBuilders - An array of query builders to execute.
+ */
 class BatchQueryBuilder {
     #builders;
     #executor;
@@ -10,9 +14,41 @@ class BatchQueryBuilder {
         this.#builders = builders;
         this.#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();
+     * ```
+     */
     async execute() {
         return this.#executor.execute(this);
     }
+    /**
+     * 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) {
         const builders = this.#builders.filter(builder => builder instanceof aggregation_query_builder_js_1.AggregationQueryBuilder ||
             builder instanceof query_builder_js_1.QueryBuilder);

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

@@ -1 +1 @@
-{"version":3,"file":"batch-query-builder.js","sourceRoot":"","sources":["../../src/batch-query-builder.ts"],"names":[],"mappings":";;;AAAA,iFAAyE;AAIzE,yDAAkD;AAuBlD,MAAa,iBAAiB;IAG5B,SAAS,CAAY;IACrB,SAAS,CAAW;IAEpB,YAAY,QAAmB,EAAE,QAAkB;QACjD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,OAAO;QAGX,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,SAAS,CACP,QAIS;QAET,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CACpC,OAAO,CAAC,EAAE,CACR,OAAO,YAAY,sDAAuB;YAC1C,OAAO,YAAY,+BAAY,CAClC,CAAC;QAEF,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAe,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO;QACL,MAAM,KAAK,GAAG,6DAA6D,CAAC;QAE5E,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;YAC5C,OAAO,OAAO,CAAC,gBAAgB,EAAE,CAAC;QACpC,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,KAAK;YACL,SAAS,EAAE;gBACT,QAAQ;aACT;SACF,CAAC;IACJ,CAAC;CACF;AArDD,8CAqDC"}
+{"version":3,"file":"batch-query-builder.js","sourceRoot":"","sources":["../../src/batch-query-builder.ts"],"names":[],"mappings":";;;AAAA,iFAAyE;AAIzE,yDAAkD;AAuBlD;;;GAGG;AACH,MAAa,iBAAiB;IAG5B,SAAS,CAAY;IACrB,SAAS,CAAW;IAEpB,YAAY,QAAmB,EAAE,QAAkB;QACjD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO;QAGX,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CACP,QAIS;QAET,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CACpC,OAAO,CAAC,EAAE,CACR,OAAO,YAAY,sDAAuB;YAC1C,OAAO,YAAY,+BAAY,CAClC,CAAC;QAEF,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAe,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO;QACL,MAAM,KAAK,GAAG,6DAA6D,CAAC;QAE5E,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;YAC5C,OAAO,OAAO,CAAC,gBAAgB,EAAE,CAAC;QACpC,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,KAAK;YACL,SAAS,EAAE;gBACT,QAAQ;aACT;SACF,CAAC;IACJ,CAAC;CACF;AArFD,8CAqFC"}

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

@@ -2,9 +2,26 @@ import type { DeleteNode } from './@types/delete.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 deleting records from the database.
+ * @template DB - The database type.
+ * @template TableName - The name of the table to delete from.
+ */
 export declare class DeleteQueryBuilder<DB extends AnyDB, TableName extends keyof DB> extends FilterableQueryBuilder<DB, TableName> {
     #private;
     constructor(node: DeleteNode, executor: Executor);
+    /**
+     * Executes the delete query.
+     * @returns A promise that resolves with the number of affected records.
+     *
+     * @example
+     * ```typescript
+     * const { affectedRecords } = await qb
+     *   .deleteFrom('users')
+     *   .where('id', '=', 1)
+     *   .execute();
+     * ```
+     */
     execute(): Promise<{
         affectedRecords: number;
     }>;

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

@@ -2,12 +2,29 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeleteQueryBuilder = void 0;
 const where_query_builder_js_1 = require("./where-query-builder.js");
+/**
+ * A query builder for deleting records from the database.
+ * @template DB - The database type.
+ * @template TableName - The name of the table to delete from.
+ */
 class DeleteQueryBuilder extends where_query_builder_js_1.FilterableQueryBuilder {
     #node;
     constructor(node, executor) {
         super(node, executor);
         this.#node = node;
     }
+    /**
+     * Executes the delete query.
+     * @returns A promise that resolves with the number of affected records.
+     *
+     * @example
+     * ```typescript
+     * const { affectedRecords } = await qb
+     *   .deleteFrom('users')
+     *   .where('id', '=', 1)
+     *   .execute();
+     * ```
+     */
     async execute() {
         const response = await this._executor.execute(this);
         return response[0];

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

@@ -1 +1 @@
-{"version":3,"file":"delete-query-builder.js","sourceRoot":"","sources":["../../src/delete-query-builder.ts"],"names":[],"mappings":";;;AAGA,qEAAkE;AAElE,MAAa,kBAGX,SAAQ,+CAAqC;IAC7C,KAAK,CAAa;IAElB,YAAY,IAAgB,EAAE,QAAkB;QAC9C,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,QAAQ,GACZ,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAgC,IAAI,CAAC,CAAC;QAEpE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;IACrB,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,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS;YAC/B,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;SACR,CAAC;IACJ,CAAC;CACF;AAxCD,gDAwCC"}
+{"version":3,"file":"delete-query-builder.js","sourceRoot":"","sources":["../../src/delete-query-builder.ts"],"names":[],"mappings":";;;AAGA,qEAAkE;AAElE;;;;GAIG;AACH,MAAa,kBAGX,SAAQ,+CAAqC;IAC7C,KAAK,CAAa;IAElB,YAAY,IAAgB,EAAE,QAAkB;QAC9C,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,QAAQ,GACZ,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAgC,IAAI,CAAC,CAAC;QAEpE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;IACrB,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,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS;YAC/B,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;SACR,CAAC;IACJ,CAAC;CACF;AApDD,gDAoDC"}

package/dist/cjs/executor.d.ts

@@ -1,4 +1,5 @@
 import { AnySubscribableQueryBuilder } from './batch-query-builder.js';
+import { SocketConnection } from './socket-connection.js';
 interface Compilable {
     compile(): {
         query: string;
@@ -7,7 +8,9 @@ interface Compilable {
 }
 export declare class Executor {
     #private;
-    constructor(baseUrl: string, apiKey: string);
+    constructor(baseUrl: string, apiKey: string, transactionId?: string, socketConnection?: SocketConnection);
+    get isInTransaction(): boolean;
+    withTransactionId(transactionId: string): Executor;
     execute<T>(builder: Compilable): Promise<T>;
     rawRequest<T>(query: string, variables: Record<string, any>, headers?: Record<string, string>): Promise<T>;
     subscribe<TResult>(builders: AnySubscribableQueryBuilder[], callback: (result: TResult) => void): Promise<{

package/dist/cjs/executor.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Executor = void 0;
-const subscription_manager_js_1 = require("./subscription-manager.js");
+const socket_connection_js_1 = require("./socket-connection.js");
 const generateUUID = () => {
     if (globalThis.crypto && globalThis.crypto.randomUUID) {
         return globalThis.crypto.randomUUID();
@@ -16,51 +16,36 @@ const generateUUID = () => {
 class Executor {
     #baseUrl;
     #apiKey;
-    #subscriptionManager;
-    constructor(baseUrl, apiKey) {
+    #socketConnection;
+    #transactionId;
+    constructor(baseUrl, apiKey, transactionId, socketConnection) {
         this.#baseUrl = baseUrl;
         this.#apiKey = apiKey;
-        this.#subscriptionManager = new subscription_manager_js_1.SubscriptionManager(this, {
-            baseUrl,
-            apiKey,
-            clientId: generateUUID(),
-        });
+        this.#transactionId = transactionId;
+        this.#socketConnection =
+            socketConnection ??
+                new socket_connection_js_1.SocketConnection({
+                    baseUrl,
+                    apiKey,
+                    clientId: generateUUID(),
+                });
+    }
+    get isInTransaction() {
+        return !!this.#transactionId;
+    }
+    withTransactionId(transactionId) {
+        return new Executor(this.#baseUrl, this.#apiKey, transactionId, this.#socketConnection);
     }
     async execute(builder) {
         const { query, variables } = builder.compile();
         return this.rawRequest(query, variables);
     }
     async rawRequest(query, variables, headers) {
-        const response = await fetch(this.#baseUrl, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${this.#apiKey}`,
-                schema: 'readable',
-                ...(headers ? { ...headers } : {}),
-            },
-            body: JSON.stringify({ query, variables }),
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Request failed with status ${response.status}: ${errorText}`);
-        }
-        const jsonResponse = await response.json();
-        if (jsonResponse.errors) {
-            throw new Error(`GraphQL errors: ${jsonResponse.errors.map(error => error.message).join('\n')}`);
-        }
-        if (jsonResponse.data) {
-            const [firstKey] = Object.keys(jsonResponse.data);
-            if (Array.isArray(jsonResponse.data[firstKey])) {
-                return jsonResponse.data[firstKey];
-            }
-            return jsonResponse.data;
-        }
-        throw new Error('Unexpected response format');
+        return this.#socketConnection.rawRequest(query, variables, headers, this.#transactionId);
     }
     subscribe(builders, callback) {
         const metadatas = builders.map(b => b._prepareMetadata());
-        return this.#subscriptionManager.subscribe(metadatas, callback);
+        return this.#socketConnection.subscribe(metadatas, callback);
     }
 }
 exports.Executor = Executor;

package/dist/cjs/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/executor.ts"],"names":[],"mappings":";;;AACA,iEAA0D;AAM1D,MAAM,YAAY,GAAG,GAAG,EAAE;IACxB,IAAI,UAAU,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACtD,OAAO,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;IACxC,CAAC;IACD,+DAA+D;IAC/D,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE;QACjE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC1C,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAa,QAAQ;IACnB,QAAQ,CAAS;IACjB,OAAO,CAAS;IAChB,iBAAiB,CAAmB;IACpC,cAAc,CAAU;IAExB,YACE,OAAe,EACf,MAAc,EACd,aAAsB,EACtB,gBAAmC;QAEnC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;QACpC,IAAI,CAAC,iBAAiB;YACpB,gBAAgB;gBAChB,IAAI,uCAAgB,CAAC;oBACnB,OAAO;oBACP,MAAM;oBACN,QAAQ,EAAE,YAAY,EAAE;iBACzB,CAAC,CAAC;IACP,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;IAC/B,CAAC;IAED,iBAAiB,CAAC,aAAqB;QACrC,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,OAAO,EACZ,aAAa,EACb,IAAI,CAAC,iBAAiB,CACvB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,OAAmB;QAClC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,UAAU,CACd,KAAa,EACb,SAA8B,EAC9B,OAAgC;QAEhC,OAAO,IAAI,CAAC,iBAAiB,CAAC,UAAU,CACtC,KAAK,EACL,SAAS,EACT,OAAO,EACP,IAAI,CAAC,cAAc,CACpB,CAAC;IACJ,CAAC;IAED,SAAS,CACP,QAAuC,EACvC,QAAmC;QAEnC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAE,CAAS,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/D,CAAC;CACF;AA9DD,4BA8DC"}

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

@@ -3,14 +3,82 @@ import type { AnyDB } from './@types/internal-types.js';
 import { NonLinkColumnNames } from './@types/query-builder.js';
 import { ResolveSelection } from './@types/type-helpers.js';
 import { Executor } from './executor.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 declare class InsertQueryBuilder<DB extends AnyDB, TableName extends keyof DB, Selection = {
     id: number;
 }> {
     #private;
     constructor(node: InsertNode, 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: Insertable<DB[TableName]> | Insertable<DB[TableName]>[]): InsertQueryBuilder<DB, TableName, Selection>;
+    /**
+     * 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<const TFields extends readonly NonLinkColumnNames<DB[TableName]>[]>(fields: TFields): InsertQueryBuilder<DB, TableName, ResolveSelection<DB, TableName, TFields, object>>;
+    /**
+     * 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();
+     * ```
+     */
     execute(): Promise<Selection[]>;
+    /**
+     * 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();
+     * ```
+     */
+    executeTakeFirst(): Promise<Selection | null>;
     compile(): {
         query: string;
         variables: Record<string, any>;

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

@@ -3,6 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InsertQueryBuilder = void 0;
 const query_builder_js_1 = require("./query-builder.js");
 const selection_builder_js_1 = require("./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.
+ */
 class InsertQueryBuilder {
     #node;
     #executor;
@@ -10,12 +16,47 @@ 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') {
@@ -31,9 +72,39 @@ 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/cjs/insert-query-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"insert-query-builder.js","sourceRoot":"","sources":["../../src/insert-query-builder.ts"],"names":[],"mappings":";;;AAKA,yDAAkD;AAClD,iEAA0D;AAE1D,MAAa,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,uCAAgB,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,+BAAY,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;AA7FD,gDA6FC"}
+{"version":3,"file":"insert-query-builder.js","sourceRoot":"","sources":["../../src/insert-query-builder.ts"],"names":[],"mappings":"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"}