mirrors/bun.sh
1
0
Fork 0
mirror of https://github.com/oven-sh/bun synced 2026-02-09 10:28:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

move types to SQL namespace

Browse Source
This commit is contained in:
Alistair Smith
2025-07-03 18:16:35 -07:00
parent a6b2c3bb18
commit 170fce2efe
2 changed files with 91 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
packages/bun-types/bun.d.ts vendored
View File

@@ -1383,33 +1383,6 @@ declare module "bun" {
prepare?: boolean;
}
/**
* Represents a SQL query that can be executed, with additional control methods
* Extends Promise to allow for async/await usage
*/
interface SQLQuery<T = any> extends Promise<T> {
/** Indicates if the query is currently executing */
active: boolean;
/** Indicates if the query has been cancelled */
cancelled: boolean;
/** Cancels the executing query */
cancel(): SQLQuery<T>;
/** Execute as a simple query, no parameters are allowed but can execute multiple commands separated by semicolons */
simple(): SQLQuery<T>;
/** Executes the query */
execute(): SQLQuery<T>;
/** Returns the raw query result */
raw(): SQLQuery<T>;
/** Returns only the values from the query result */
values(): SQLQuery<T>;
}
namespace SQL {
type AwaitPromisesArray<T extends Array<PromiseLike<any>>> = {
[K in keyof T]: Awaited<T[K]>;
@@ -1417,24 +1390,60 @@ declare module "bun" {
type ContextCallbackResult<T> = T extends Array<PromiseLike<any>> ? AwaitPromisesArray<T> : Awaited<T>;
type ContextCallback<T, SQL> = (sql: SQL) => Promise<T>;
/**
* Represents a SQL query that can be executed, with additional control methods
* Extends Promise to allow for async/await usage
*/
interface Query<T = any> extends Promise<T> {
/** Indicates if the query is currently executing */
active: boolean;
/** Indicates if the query has been cancelled */
cancelled: boolean;
/** Cancels the executing query */
cancel(): SQLQuery<T>;
/** Execute as a simple query, no parameters are allowed but can execute multiple commands separated by semicolons */
simple(): SQLQuery<T>;
/** Executes the query */
execute(): SQLQuery<T>;
/** Returns the raw query result */
raw(): SQLQuery<T>;
/** Returns only the values from the query result */
values(): SQLQuery<T>;
}
/**
* Callback function type for transaction contexts
* @param sql Function to execute SQL queries within the transaction
*/
type TransactionContextCallback<T> = ContextCallback<T, TransactionSQL>;
/**
* Callback function type for savepoint contexts
* @param sql Function to execute SQL queries within the savepoint
*/
type SavepointContextCallback<T> = SQL.ContextCallback<T, SavepointSQL>;
interface Helper<T> {
readonly value: T[];
readonly columns: (keyof T)[];
}
}
/**
* Callback function type for transaction contexts
* @param sql Function to execute SQL queries within the transaction
*/
type SQLTransactionContextCallback<T> = SQL.ContextCallback<T, TransactionSQL>;
/** @deprecated Use {@link SQL.Query} */
type SQLQuery<T = any> = SQL.Query<T>;
/**
* Callback function type for savepoint contexts
* @param sql Function to execute SQL queries within the savepoint
*/
type SQLSavepointContextCallback<T> = SQL.ContextCallback<T, SavepointSQL>;
/** @deprecated Use {@link SQL.TransactionContextCallback} */
type SQLTransactionContextCallback<T> = SQL.TransactionContextCallback<T>;
interface SQLHelper<T> {
readonly value: T[];
readonly columns: (keyof T)[];
}
/** @deprecated Use {@link SQL.SavepointContextCallback} */
type SQLSavepointContextCallback<T> = SQL.SavepointContextCallback<T>;
/**
* Main SQL client interface providing connection and transaction management
@@ -1447,12 +1456,12 @@ declare module "bun" {
* const [user] = await sql`select * from users where id = ${1}`;
* ```
*/
<T = any>(strings: TemplateStringsArray, ...values: unknown[]): SQLQuery<T>;
<T = any>(strings: TemplateStringsArray, ...values: unknown[]): SQL.Query<T>;
/**
* Execute a SQL query using a string
*/
<T = any>(string: string): SQLQuery<T>;
<T = any>(string: string): SQL.Query<T>;
/**
* Helper function for inserting an object into a query
@@ -1472,7 +1481,7 @@ declare module "bun" {
<T extends { [Key in PropertyKey]: unknown }, Keys extends keyof T = keyof T>(
obj: T | T[] | readonly T[],
...columns: readonly Keys[]
): SQLHelper<Pick<T, Keys>>;
): SQL.Helper<Pick<T, Keys>>;
/**
* Helper function for inserting any serializable value into a query
@@ -1482,7 +1491,7 @@ declare module "bun" {
* const result = await sql`SELECT * FROM users WHERE id IN ${sql([1, 2, 3])}`;
* ```
*/
<T>(value: T): SQLHelper<T>;
<T>(value: T): SQL.Helper<T>;
/**
* Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL
@@ -1607,7 +1616,7 @@ declare module "bun" {
* return [user, account]
* })
*/
begin<const T>(fn: SQLTransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
begin<const T>(fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
/**
* Begins a new transaction with options.
@@ -1635,7 +1644,7 @@ declare module "bun" {
* return [user, account]
* })
*/
begin<const T>(options: string, fn: SQLTransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
begin<const T>(options: string, fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
/**
* Alternative method to begin a transaction.
@@ -1664,7 +1673,7 @@ declare module "bun" {
* return [user, account]
* })
*/
transaction<const T>(fn: SQLTransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
transaction<const T>(fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
/**
* Alternative method to begin a transaction with options
@@ -1694,7 +1703,7 @@ declare module "bun" {
* return [user, account]
* });
*/
transaction<const T>(options: string, fn: SQLTransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
transaction<const T>(options: string, fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
/**
* Begins a distributed transaction
@@ -1715,13 +1724,13 @@ declare module "bun" {
*/
beginDistributed<const T>(
name: string,
fn: SQLTransactionContextCallback<T>,
fn: SQL.TransactionContextCallback<T>,
): Promise<SQL.ContextCallbackResult<T>>;
/** Alternative method to begin a distributed transaction
* @alias {@link beginDistributed}
*/
distributed<const T>(name: string, fn: SQLTransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
distributed<const T>(name: string, fn: SQL.TransactionContextCallback<T>): Promise<SQL.ContextCallbackResult<T>>;
/**If you know what you're doing, you can use unsafe to pass any string you'd like.
* Please note that this can lead to SQL injection if you're not careful.

62
test/integration/bun-types/fixture/sql.ts
View File

@@ -111,14 +111,14 @@ expectType(
expectType(tx).is<readonly [[9], [10]]>();
}
expectType(sql1.unsafe("SELECT * FROM users")).is<Bun.SQLQuery>();
expectType(sql1.unsafe<{ id: string }[]>("SELECT * FROM users")).is<Bun.SQLQuery<{ id: string }[]>>();
expectType(sql1.file("query.sql", [1, 2, 3])).is<Bun.SQLQuery>();
expectType(sql1.unsafe("SELECT * FROM users")).is<Bun.SQL.Query>();
expectType(sql1.unsafe<{ id: string }[]>("SELECT * FROM users")).is<Bun.SQL.Query<{ id: string }[]>>();
expectType(sql1.file("query.sql", [1, 2, 3])).is<Bun.SQL.Query>();
sql1.reserve().then(reserved => {
reserved.release();
expectType(reserved<[8]>`SELECT 8`).is<Bun.SQLQuery<[8]>>();
expectType(reserved<[8]>`SELECT 8`).is<Bun.SQL.Query<[8]>>();
});
sql1.begin(async txn => {
@@ -151,23 +151,23 @@ sql1.begin("read write", 123);
// @ts-expect-error
sql1.transaction("read write", 123);
const sqlQueryAny: Bun.SQLQuery = {} as any;
const sqlQueryNumber: Bun.SQLQuery<number> = {} as any;
const sqlQueryString: Bun.SQLQuery<string> = {} as any;
const sqlQueryAny: Bun.SQL.Query = {} as any;
const sqlQueryNumber: Bun.SQL.Query<number> = {} as any;
const sqlQueryString: Bun.SQL.Query<string> = {} as any;
expectAssignable<Promise<any>>(sqlQueryAny);
expectAssignable<Promise<number>>(sqlQueryNumber);
expectAssignable<Promise<string>>(sqlQueryString);
expectType(sqlQueryNumber).is<Bun.SQLQuery<number>>();
expectType(sqlQueryString).is<Bun.SQLQuery<string>>();
expectType(sqlQueryNumber).is<Bun.SQLQuery<number>>();
expectType(sqlQueryNumber).is<Bun.SQL.Query<number>>();
expectType(sqlQueryString).is<Bun.SQL.Query<string>>();
expectType(sqlQueryNumber).is<Bun.SQL.Query<number>>();
const queryA = sql`SELECT 1`;
expectType(queryA).is<Bun.SQLQuery>();
expectType(queryA).is<Bun.SQL.Query>();
const queryB = sql({ foo: "bar" });
expectType(queryB).is<Bun.SQLHelper<{ foo: string }>>();
expectType(queryB).is<Bun.SQL.Helper<{ foo: string }>>();
expectType(sql).is<Bun.SQL>();
@@ -180,18 +180,18 @@ const spCb = (async sql => [sql<[2]>`SELECT 2`]) satisfies Bun.SQLSavepointConte
expectType(await sql.begin(txCb)).is<[1][]>();
expectType(await sql.begin(spCb)).is<[2][]>();
expectType(queryA.cancel()).is<Bun.SQLQuery>();
expectType(queryA.simple()).is<Bun.SQLQuery>();
expectType(queryA.execute()).is<Bun.SQLQuery>();
expectType(queryA.raw()).is<Bun.SQLQuery>();
expectType(queryA.values()).is<Bun.SQLQuery>();
expectType(queryA.cancel()).is<Bun.SQL.Query>();
expectType(queryA.simple()).is<Bun.SQL.Query>();
expectType(queryA.execute()).is<Bun.SQL.Query>();
expectType(queryA.raw()).is<Bun.SQL.Query>();
expectType(queryA.values()).is<Bun.SQL.Query>();
declare const queryNum: Bun.SQLQuery<number>;
expectType(queryNum.cancel()).is<Bun.SQLQuery<number>>();
expectType(queryNum.simple()).is<Bun.SQLQuery<number>>();
expectType(queryNum.execute()).is<Bun.SQLQuery<number>>();
expectType(queryNum.raw()).is<Bun.SQLQuery<number>>();
expectType(queryNum.values()).is<Bun.SQLQuery<number>>();
declare const queryNum: Bun.SQL.Query<number>;
expectType(queryNum.cancel()).is<Bun.SQL.Query<number>>();
expectType(queryNum.simple()).is<Bun.SQL.Query<number>>();
expectType(queryNum.execute()).is<Bun.SQL.Query<number>>();
expectType(queryNum.raw()).is<Bun.SQL.Query<number>>();
expectType(queryNum.values()).is<Bun.SQL.Query<number>>();
expectType(await queryNum.cancel()).is<number>();
expectType(await queryNum.simple()).is<number>();
@@ -200,7 +200,7 @@ expectType(await queryNum.raw()).is<number>();
expectType(await queryNum.values()).is<number>();
expectType(sql({ name: "Alice", email: "alice@example.com" })).is<
Bun.SQLHelper<{
Bun.SQL.Helper<{
name: string;
email: string;
}>
@@ -212,7 +212,7 @@ expectType(
{ name: "Bob", email: "bob@example.com" },
]),
).is<
Bun.SQLHelper<{
Bun.SQL.Helper<{
name: string;
email: string;
}>
@@ -221,7 +221,7 @@ expectType(
const userWithAge = { name: "Alice", email: "alice@example.com", age: 25 };
expectType(sql(userWithAge, "name", "email")).is<
Bun.SQLHelper<{
Bun.SQL.Helper<{
name: string;
email: string;
}>
@@ -231,13 +231,13 @@ const users = [
{ id: 1, name: "Alice" },
{ id: 2, name: "Bob" },
];
expectType(sql(users, "id")).is<Bun.SQLHelper<{ id: number }>>();
expectType(sql(users, "id")).is<Bun.SQL.Helper<{ id: number }>>();
expectType(sql([1, 2, 3])).is<Bun.SQLHelper<number[]>>();
expectType(sql([1, 2, 3] as const)).is<Bun.SQLHelper<readonly [1, 2, 3]>>();
expectType(sql([1, 2, 3])).is<Bun.SQL.Helper<number[]>>();
expectType(sql([1, 2, 3] as const)).is<Bun.SQL.Helper<readonly [1, 2, 3]>>();
expectType(sql("users")).is<Bun.SQLQuery<any>>();
expectType(sql<1>("users")).is<Bun.SQLQuery<1>>();
expectType(sql("users")).is<Bun.SQL.Query<any>>();
expectType(sql<1>("users")).is<Bun.SQL.Query<1>>();
// @ts-expect-error - missing key in object
sql(user, "notAKey");