kern-db 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +34 -2
- package/dist/array-BLt8ZNR5.mjs +77 -0
- package/dist/builder.d.mts +4 -0
- package/dist/builder.mjs +1 -0
- package/dist/bytea-DNZ_ftio.mjs +92 -0
- package/dist/database-BkWPkXG5.mjs +1470 -0
- package/dist/driver-CSfbXOBJ.d.mts +77 -0
- package/dist/driver-error-26zcdHeU.mjs +88 -0
- package/dist/index.d.mts +360 -0
- package/dist/index.mjs +5 -0
- package/dist/node-postgres.d.mts +8 -0
- package/dist/node-postgres.mjs +177 -0
- package/dist/postgres-js.d.mts +9 -0
- package/dist/postgres-js.mjs +86 -0
- package/dist/query-BrvYBvWC.d.mts +428 -0
- package/dist/query-FKBN7BMY.mjs +439 -0
- package/dist/testing.d.mts +101 -0
- package/dist/testing.mjs +741 -0
- package/dist/type-CbrtxvDF.d.mts +113 -0
- package/dist/types-Dl2oicjV.mjs +186 -0
- package/dist/types.d.mts +53 -0
- package/dist/types.mjs +4 -0
- package/package.json +69 -4
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
import { a as TextValue, i as SqlStatement, n as Driver, r as DriverResult } from "./driver-CSfbXOBJ.mjs";
|
|
2
|
+
import { c as Type, d as TypeOutput, i as AnyType } from "./type-CbrtxvDF.mjs";
|
|
3
|
+
/**
|
|
4
|
+
* How a query returns its rows: `many` as an array; `one` as one row, rejecting without it; `nullable` as one row or `null` without it; `optional` as one row or `undefined` without it.
|
|
5
|
+
*
|
|
6
|
+
* A query of one row rejects several rows, since the mode implies no SQL limit.
|
|
7
|
+
*/
|
|
8
|
+
type ResultRows = "many" | "one" | "nullable" | "optional";
|
|
9
|
+
/** How the rows of a query become its result, apart from its fields. */
|
|
10
|
+
interface ResultMode {
|
|
11
|
+
readonly rows: ResultRows;
|
|
12
|
+
/** A row is the value of its only field instead of a record. */
|
|
13
|
+
readonly value: boolean;
|
|
14
|
+
}
|
|
15
|
+
/** Rows mode after `take`: `many` becomes `one`; the modes of one row stay. */
|
|
16
|
+
type OneRow<Rows extends ResultRows> = Rows extends "many" ? "one" : Rows;
|
|
17
|
+
/** Rows mode after `pluck`: `nullable` becomes `optional`; the other modes stay. */
|
|
18
|
+
type ValueRows<Rows extends ResultRows> = Rows extends "nullable" ? "optional" : Rows;
|
|
19
|
+
/** Rows mode after `get`: `many` becomes `one` and `nullable` becomes `optional`; `one` and `optional` stay. */
|
|
20
|
+
type OneValueRows<Rows extends ResultRows> = Rows extends "many" ? "one" : Rows extends "nullable" ? "optional" : Rows;
|
|
21
|
+
/** Result of rows of `Result` returned in rows mode `Rows`; a union of modes gives the union of their results. */
|
|
22
|
+
type ResultByRows<Result, Rows extends ResultRows> = Rows extends "many" ? Result[] : Rows extends "one" ? Result : Rows extends "nullable" ? Result | null : Result | undefined;
|
|
23
|
+
/** Returns the rows mode after `pluck` of a query of rows mode `rows`, as `ValueRows` gives it in types. */
|
|
24
|
+
declare function toValueRows(rows: ResultRows): ResultRows;
|
|
25
|
+
/** Error thrown when a query of one row finds no row, unless the code that decodes the row tells another reason, such as a broken guarantee of the row. */
|
|
26
|
+
declare class NotFoundError extends Error {
|
|
27
|
+
readonly name = "NotFoundError";
|
|
28
|
+
/** Path of the missing rows nested in a field, such as `user` or `fields[2].form`, after the index of the row of a query of rows `many`, such as `[2].form`; `undefined` when the query itself finds no row. */
|
|
29
|
+
readonly path: string | undefined;
|
|
30
|
+
constructor(message: string, path?: string);
|
|
31
|
+
}
|
|
32
|
+
/** Field of a flat result: the key of a record, which names the result column of its value, and the type that decodes the value. */
|
|
33
|
+
interface FlatField {
|
|
34
|
+
readonly key: string;
|
|
35
|
+
readonly type: AnyType;
|
|
36
|
+
}
|
|
37
|
+
/** How a flat result decodes the result of a statement. */
|
|
38
|
+
interface FlatResultPlan extends ResultMode {
|
|
39
|
+
/**
|
|
40
|
+
* Fields read from the result columns of their keys, or from the only column for a value, whatever its name; `undefined` for a result that is the number of the rows of the command tag.
|
|
41
|
+
*
|
|
42
|
+
* The key of the field of a value names it only in decoding errors.
|
|
43
|
+
*/
|
|
44
|
+
readonly fields: readonly FlatField[] | undefined;
|
|
45
|
+
}
|
|
46
|
+
/** Error thrown when a row does not match the fields of its query, or a value fails to decode or to convert; the failure is its cause. */
|
|
47
|
+
declare class ResultDecodeError extends Error {
|
|
48
|
+
/**
|
|
49
|
+
* Path of the value from its result field, such as `fields[2].label`, after the index of the row of a query of rows `many`, such as `[2].label`.
|
|
50
|
+
*
|
|
51
|
+
* A conversion of a row that fails has the path of its row, such as `fields[2]` or `[2]`, and a conversion of nested rows as a whole the path of their field, such as `fields`.
|
|
52
|
+
* It is `undefined` for a failure that no value causes, such as a row of another width than the fields, and for a conversion that fails on the only row or the whole result of a query.
|
|
53
|
+
*/
|
|
54
|
+
readonly path: string | undefined;
|
|
55
|
+
readonly name = "ResultDecodeError";
|
|
56
|
+
constructor(message: string,
|
|
57
|
+
/**
|
|
58
|
+
* Path of the value from its result field, such as `fields[2].label`, after the index of the row of a query of rows `many`, such as `[2].label`.
|
|
59
|
+
*
|
|
60
|
+
* A conversion of a row that fails has the path of its row, such as `fields[2]` or `[2]`, and a conversion of nested rows as a whole the path of their field, such as `fields`.
|
|
61
|
+
* It is `undefined` for a failure that no value causes, such as a row of another width than the fields, and for a conversion that fails on the only row or the whole result of a query.
|
|
62
|
+
*/
|
|
63
|
+
path: string | undefined, options?: ErrorOptions);
|
|
64
|
+
}
|
|
65
|
+
/** Tells whether `key` can be a key of a decoded record, such as a column key: assigning `__proto__` would change the prototype of the record instead. */
|
|
66
|
+
declare function isRecordKey(key: string): boolean;
|
|
67
|
+
/**
|
|
68
|
+
* Returns the only row of `rows` of a query of one row in the rows mode of `plan`, or `undefined` without a row.
|
|
69
|
+
*
|
|
70
|
+
* It rejects several rows, since the query may have no limit, such as a query that requires at most one match, and no row of rows `one` with `NotFoundError`.
|
|
71
|
+
*/
|
|
72
|
+
declare function takeOnlyRow<Row>(plan: ResultMode, rows: readonly Row[]): Row | undefined;
|
|
73
|
+
/** Returns the result of a query of rows `nullable` or `optional` in the mode of `plan` without a row: `null` or `undefined`. */
|
|
74
|
+
declare function toMissingResult(plan: ResultMode): null | undefined;
|
|
75
|
+
/**
|
|
76
|
+
* Creates the error of a result that fails to decode or to convert, with the failure `cause` as its cause, whose message follows `message`.
|
|
77
|
+
*
|
|
78
|
+
* `path` is the path of the failing value, as `ResultDecodeError` describes it.
|
|
79
|
+
*/
|
|
80
|
+
declare function createResultDecodeError(message: string, path: string | undefined, cause: unknown): ResultDecodeError;
|
|
81
|
+
/** Creates the error of a value at `path` of a result that fails to decode, such as `[2].label`, with the failure as its cause. */
|
|
82
|
+
declare function createFieldDecodeError(path: string, cause: unknown): ResultDecodeError;
|
|
83
|
+
/** Value that a parameter takes without a type, encoded by its JavaScript type; `null` is `NULL`. */
|
|
84
|
+
type UntypedValue = string | number | bigint | boolean | null | Date | Uint8Array;
|
|
85
|
+
/**
|
|
86
|
+
* Checks that a parameter takes `value` without a type, such as an interpolated value of a template, so that an error points at the template rather than at the compilation of its statement.
|
|
87
|
+
*
|
|
88
|
+
* It rejects `undefined` and a value that a parameter does not take without a type, such as an object or an array.
|
|
89
|
+
*/
|
|
90
|
+
declare function assertUntypedValue(value: unknown): asserts value is UntypedValue;
|
|
91
|
+
/** Encodes the value of a parameter with `type`, or by its JavaScript type without one; it rejects `undefined`, and a value that a parameter does not take without a type. */
|
|
92
|
+
declare function encodeParameter(value: unknown, type: AnyType | undefined): TextValue;
|
|
93
|
+
/** Adds `value` to `parameters` of a statement and returns its placeholder, such as `$1`, rejecting more parameters than PostgreSQL takes. */
|
|
94
|
+
declare function bindParameter(parameters: TextValue[], value: TextValue): string;
|
|
95
|
+
/**
|
|
96
|
+
* SQL fragment: text with the parameters and the fragments interpolated into it, which `sql`, `identifier`, and `param` create.
|
|
97
|
+
*
|
|
98
|
+
* It is immutable, and its parameters are numbered only when a statement is compiled, so a fragment can be interpolated into several statements.
|
|
99
|
+
*/
|
|
100
|
+
declare class SqlFragment {
|
|
101
|
+
/** Text around the values; always one element longer than `values`. */
|
|
102
|
+
readonly strings: readonly string[];
|
|
103
|
+
/** Interpolated values: a fragment, the parameter of `param`, or the value of a parameter without a type. */
|
|
104
|
+
readonly values: readonly unknown[];
|
|
105
|
+
/** Mark of fragments for types; absent at runtime. */
|
|
106
|
+
private readonly fragmentBrand;
|
|
107
|
+
constructor(
|
|
108
|
+
/** Text around the values; always one element longer than `values`. */
|
|
109
|
+
strings: readonly string[],
|
|
110
|
+
/** Interpolated values: a fragment, the parameter of `param`, or the value of a parameter without a type. */
|
|
111
|
+
values: readonly unknown[]);
|
|
112
|
+
}
|
|
113
|
+
/** Value that the template of `sql` interpolates: a fragment, or the value of a parameter, encoded by its JavaScript type. */
|
|
114
|
+
type SqlValue = UntypedValue | SqlFragment;
|
|
115
|
+
/**
|
|
116
|
+
* Builds a SQL fragment.
|
|
117
|
+
*
|
|
118
|
+
* An interpolated fragment, such as of `identifier` or `param`, stays SQL, and another value becomes a parameter: a string, a number, a bigint, a Boolean, `null` for `NULL`, a `Date`, or a `Uint8Array`.
|
|
119
|
+
* It rejects any other value, such as an object or an array: pass JSON or an array with `param` and its type.
|
|
120
|
+
*/
|
|
121
|
+
declare function sql(strings: TemplateStringsArray, ...values: SqlValue[]): SqlFragment;
|
|
122
|
+
/**
|
|
123
|
+
* Creates a SQL fragment of a quoted name, such as of a table or a column known only at runtime.
|
|
124
|
+
*
|
|
125
|
+
* Several names make a qualified name, such as `identifier(schema, table)` for `"schema"."table"`.
|
|
126
|
+
* The fragment has no parameters, so the template of a script takes it.
|
|
127
|
+
*/
|
|
128
|
+
declare function identifier(...names: [string, ...string[]]): SqlFragment;
|
|
129
|
+
/**
|
|
130
|
+
* Creates a SQL fragment of a parameter that `type` encodes, such as of JSON or of an array, cast to its cast type, such as `$1::jsonb`.
|
|
131
|
+
*
|
|
132
|
+
* The cast omits type parameters, such as `$1::numeric` for `numeric(10,2)`, so that their precision, scale, or length do not constrain the value.
|
|
133
|
+
*/
|
|
134
|
+
declare function param<Output, Input>(type: Type<Output, Input>, value: NoInfer<Input>): SqlFragment;
|
|
135
|
+
/** Receives the parameters of a statement in the order of its text as a fragment renders, and returns their placeholders, such as `$1`. */
|
|
136
|
+
interface ParameterBinder {
|
|
137
|
+
/** Adds the parameter of the text representation `value`. */
|
|
138
|
+
bind(value: TextValue): string;
|
|
139
|
+
/**
|
|
140
|
+
* Adds the parameter of a fragment of `param`, of the text representation `value`.
|
|
141
|
+
*
|
|
142
|
+
* `key` is the same object wherever a statement repeats the fragment, so that a binder can give its parameter one placeholder: the cast types it the same at every place.
|
|
143
|
+
*/
|
|
144
|
+
bindParam(key: object, value: TextValue): string;
|
|
145
|
+
}
|
|
146
|
+
/** Renders `fragment` into SQL text, encoding its parameters and binding them with `binder` in the order of the text. */
|
|
147
|
+
declare function renderFragment(fragment: SqlFragment, binder: ParameterBinder): string;
|
|
148
|
+
/**
|
|
149
|
+
* Physical database: the connections of a driver, and the ambient transactions and sessions that route statements to them.
|
|
150
|
+
*
|
|
151
|
+
* Disposing it, such as with `await using`, closes it.
|
|
152
|
+
*/
|
|
153
|
+
interface Database extends AsyncDisposable {
|
|
154
|
+
/**
|
|
155
|
+
* Executes a script of statements without parameters, such as DDL separated by semicolons, in the ambient transaction or session, or on the pool outside of one; outside a transaction, PostgreSQL runs them in one implicit transaction.
|
|
156
|
+
*
|
|
157
|
+
* The script must not start or end transactions, which the database tracks.
|
|
158
|
+
*/
|
|
159
|
+
script(text: string): Promise<void>;
|
|
160
|
+
/**
|
|
161
|
+
* Executes the script of the template as `script` of its text does.
|
|
162
|
+
*
|
|
163
|
+
* It interpolates SQL fragments without parameters, such as a name of `identifier`; it rejects values, since a script has no parameters.
|
|
164
|
+
*/
|
|
165
|
+
script(strings: TemplateStringsArray, ...values: SqlValue[]): Promise<void>;
|
|
166
|
+
/**
|
|
167
|
+
* Starts a query of the SQL statement of the template, which resolves to the number of the rows of its command tag when awaited, such as the rows that an `UPDATE` changes; `select`, `get`, and `pluck` return the fields of its rows instead.
|
|
168
|
+
*
|
|
169
|
+
* It interpolates SQL fragments, such as a name of `identifier`, as SQL, and other values as parameters, as `sql` does.
|
|
170
|
+
*/
|
|
171
|
+
query(strings: TemplateStringsArray, ...values: SqlValue[]): SqlQuery<InitialSqlQueryState>;
|
|
172
|
+
/** Executes a compiled statement, such as of `$compile` of a `Db`, in the ambient transaction or session, or on the pool outside of one unless the database was created with `test: true`. */
|
|
173
|
+
execute(statement: SqlStatement): Promise<DriverResult>;
|
|
174
|
+
/**
|
|
175
|
+
* Runs `callback` in a transaction that queries of every bound schema join automatically.
|
|
176
|
+
*
|
|
177
|
+
* Inside an existing transaction, it starts a nested transaction.
|
|
178
|
+
*/
|
|
179
|
+
transaction<T>(callback: () => Promise<T>, options?: TransactionOptions): Promise<T>;
|
|
180
|
+
/**
|
|
181
|
+
* Runs `callback` in the current transaction without a nested transaction, or in a new transaction outside of one.
|
|
182
|
+
*
|
|
183
|
+
* A rejection of a callback that joined a transaction does not undo its changes: the enclosing transaction commits them unless it fails too.
|
|
184
|
+
* A test transaction is not a transaction to join: there, it starts a nested transaction where it starts a transaction in production.
|
|
185
|
+
*/
|
|
186
|
+
ensureTransaction<T>(callback: () => Promise<T>): Promise<T>;
|
|
187
|
+
/** Tells whether the code runs in a transaction, not counting test transactions, so that code under test sees what it sees in production. */
|
|
188
|
+
isInTransaction(): boolean;
|
|
189
|
+
/**
|
|
190
|
+
* Tells whether a statement of the code runs in a transaction block of PostgreSQL, counting test transactions, such as to choose a statement that PostgreSQL rejects there, `CREATE INDEX CONCURRENTLY`.
|
|
191
|
+
*
|
|
192
|
+
* It is `false` in a session outside its transactions.
|
|
193
|
+
*/
|
|
194
|
+
isInTransactionBlock(): boolean;
|
|
195
|
+
/**
|
|
196
|
+
* Runs `callback` in a session: on one connection outside a transaction, such as for statements that PostgreSQL rejects in a transaction block and that share a setting of the connection, such as its search path.
|
|
197
|
+
*
|
|
198
|
+
* Statements of every bound schema join the session automatically, each in a transaction of its own, and `transaction` in the callback starts a transaction on the connection of the session.
|
|
199
|
+
* A rejection of `callback` undoes nothing.
|
|
200
|
+
* It rejects inside a transaction, also a test transaction, inside another session, and on a database created with `test: true`.
|
|
201
|
+
*/
|
|
202
|
+
session<T>(callback: () => Promise<T>, options?: SessionOptions): Promise<T>;
|
|
203
|
+
/**
|
|
204
|
+
* Takes the advisory lock of `key` until the transaction ends, waiting while another transaction or session holds it, such as to keep processes from running the same job at once.
|
|
205
|
+
*
|
|
206
|
+
* It rejects where `isInTransaction()` is `false`, since outside a transaction the lock would end with its statement; in a session, take the lock with `tryLock`, which does not wait.
|
|
207
|
+
* A nested transaction that rolls back releases the locks it took.
|
|
208
|
+
*/
|
|
209
|
+
lock(key: string): Promise<void>;
|
|
210
|
+
/**
|
|
211
|
+
* Takes the advisory lock of `key` unless another transaction or session holds it, and tells whether it took it, such as to skip a job that another process is running.
|
|
212
|
+
*
|
|
213
|
+
* In a transaction, it holds the lock until the transaction ends, as `lock` does; in a session outside its transactions, until the session ends.
|
|
214
|
+
* It rejects outside both, since the lock would end with its statement; a test transaction alone does not count.
|
|
215
|
+
*/
|
|
216
|
+
tryLock(key: string): Promise<boolean>;
|
|
217
|
+
/**
|
|
218
|
+
* Takes the advisory lock of `key` in a session until the session ends, calling `tryLock` again after a pause until it takes the lock, such as to let one process at a time run statements outside a transaction.
|
|
219
|
+
*
|
|
220
|
+
* It rejects outside a session, and in a transaction, where `lock` waits for the lock.
|
|
221
|
+
* Once `signal` of `options` aborts, such as `AbortSignal.timeout(60_000)`, it makes no more attempts and rejects with the reason of the signal, unless the attempt that is running takes the lock.
|
|
222
|
+
*/
|
|
223
|
+
pollLock(key: string, options?: PollLockOptions): Promise<void>;
|
|
224
|
+
/** Rolls back the open test fixtures and closes the connections of the driver once the running transactions and sessions end. */
|
|
225
|
+
close(): Promise<void>;
|
|
226
|
+
}
|
|
227
|
+
/** Isolation level of a transaction in PostgreSQL. */
|
|
228
|
+
type IsolationLevel = "read committed" | "repeatable read" | "serializable";
|
|
229
|
+
/** Options of `transaction` of a `Database` and `$transaction` of a `Db`. */
|
|
230
|
+
interface TransactionOptions {
|
|
231
|
+
/**
|
|
232
|
+
* Isolation level of the transaction, such as `serializable`.
|
|
233
|
+
*
|
|
234
|
+
* A nested transaction runs at the level of its transaction: given another level, it rejects.
|
|
235
|
+
*/
|
|
236
|
+
isolation?: IsolationLevel;
|
|
237
|
+
/**
|
|
238
|
+
* PostgreSQL schemas where the unqualified names of the statements of the transaction resolve, in their order, such as the schema of a tenant followed by the schema of extensions.
|
|
239
|
+
*
|
|
240
|
+
* It applies to the statements of the callback, including those of its nested transactions, until the transaction ends; a nested transaction then restores the search path of the enclosing transaction.
|
|
241
|
+
*/
|
|
242
|
+
searchPath?: readonly string[];
|
|
243
|
+
}
|
|
244
|
+
/** Options of `session` of a `Database` and `$session` of a `Db`. */
|
|
245
|
+
interface SessionOptions {
|
|
246
|
+
/**
|
|
247
|
+
* PostgreSQL schemas where the unqualified names of the statements of the session resolve, in their order, such as the schema of a tenant followed by the schema of extensions.
|
|
248
|
+
*
|
|
249
|
+
* It applies to the statements of the callback, including those of its transactions, until the session ends, which restores the search path that its connection had.
|
|
250
|
+
*/
|
|
251
|
+
searchPath?: readonly string[];
|
|
252
|
+
}
|
|
253
|
+
/** Options of `pollLock` of a `Database` and `$pollLock` of a `Db`. */
|
|
254
|
+
interface PollLockOptions {
|
|
255
|
+
/** Signal that stops waiting for the lock, such as `AbortSignal.timeout(60_000)`: once it aborts, `pollLock` makes no more attempts. */
|
|
256
|
+
signal?: AbortSignal;
|
|
257
|
+
}
|
|
258
|
+
/** Options of `createDatabase`. */
|
|
259
|
+
interface DatabaseOptions {
|
|
260
|
+
driver: Driver;
|
|
261
|
+
/** Rejects queries and transactions outside the test transactions and the seeds of test fixtures of `kern-db/testing`, so that every statement of the tests runs in a transaction that rolls back. */
|
|
262
|
+
test?: boolean;
|
|
263
|
+
/**
|
|
264
|
+
* Receives a failure to release the connection of a transaction or a session, or to release the advisory locks or restore the settings of a session, such as to log it; the failure does not change the result or error of the transaction or session.
|
|
265
|
+
*
|
|
266
|
+
* Without it, the failure goes to `console.error`.
|
|
267
|
+
*/
|
|
268
|
+
onReleaseError?: (error: unknown) => void;
|
|
269
|
+
}
|
|
270
|
+
/**
|
|
271
|
+
* Checks whether `value` is a database of `createDatabase`, also of another copy of kern-db, such as to reject a client of PostgreSQL or a `Db` of kern-orm passed instead of a database.
|
|
272
|
+
*
|
|
273
|
+
* It checks the brand that `createDatabase` sets, so it rejects a spread copy of a database.
|
|
274
|
+
*/
|
|
275
|
+
declare function isDatabase(value: unknown): value is Database;
|
|
276
|
+
/** Creates a database over a driver. */
|
|
277
|
+
declare function createDatabase({ driver, ...options }: DatabaseOptions): Database;
|
|
278
|
+
/** Compiles the statement of a query of SQL text, each time the query executes or compiles, so that what it reads when it compiles, such as a PostgreSQL schema of the current tenant, is current. */
|
|
279
|
+
type StatementSource = () => SqlStatement;
|
|
280
|
+
/** Types of the fields of the rows of a query of SQL text by the names of the result columns that they decode. */
|
|
281
|
+
interface FieldTypes {
|
|
282
|
+
readonly [key: string]: AnyType;
|
|
283
|
+
readonly [key: symbol]: never;
|
|
284
|
+
}
|
|
285
|
+
/** Record of the values that the types of fields `F` decode. */
|
|
286
|
+
type DecodedFields<F extends FieldTypes> = { -readonly [K in keyof F]: TypeOutput<F[K]>; };
|
|
287
|
+
/**
|
|
288
|
+
* State in types of a query of SQL text: its result, which is the number of the rows of its command tag until a selection returns their fields, how its rows become its result, and the rows mode of the rows that its statement returns.
|
|
289
|
+
*
|
|
290
|
+
* Methods change only their own parts of the state.
|
|
291
|
+
*/
|
|
292
|
+
interface SqlQueryState {
|
|
293
|
+
/** Record of a row, the value of its only column for a query of `get` or `pluck`, or the number of the rows. */
|
|
294
|
+
readonly result: unknown;
|
|
295
|
+
/** How the rows become the result. */
|
|
296
|
+
readonly rows: ResultRows;
|
|
297
|
+
/** Whether a row is the value of its only column instead of a record. */
|
|
298
|
+
readonly value: boolean;
|
|
299
|
+
/** Rows mode of the rows of the statement, which `select`, `get`, and `pluck` return. */
|
|
300
|
+
readonly returned: ResultRows;
|
|
301
|
+
/** Whether the query returns the fields of the rows of the statement rather than their number. */
|
|
302
|
+
readonly returning: boolean;
|
|
303
|
+
}
|
|
304
|
+
/** State of a query of SQL text that returns the number of the rows of its command tag. */
|
|
305
|
+
interface InitialSqlQueryState extends SqlQueryState {
|
|
306
|
+
readonly result: number;
|
|
307
|
+
readonly rows: "one";
|
|
308
|
+
readonly value: true;
|
|
309
|
+
readonly returned: "many";
|
|
310
|
+
readonly returning: false;
|
|
311
|
+
}
|
|
312
|
+
/** Result of a query of SQL text of state `S`. */
|
|
313
|
+
type SqlQueryResult<S extends SqlQueryState> = ResultByRows<S["result"], S["rows"]>;
|
|
314
|
+
/** State `S` of a query of SQL text with the parts of `Changes` replaced. */
|
|
315
|
+
type ChangeSqlQueryState<S extends SqlQueryState, Changes extends Partial<SqlQueryState>> = { readonly [K in keyof SqlQueryState]: K extends keyof Changes ? Changes[K] : S[K]; } & {};
|
|
316
|
+
/** State of a query of SQL text that returns the number of the rows or their records, which `select` applies to. */
|
|
317
|
+
type RecordSqlQueryState = SqlQueryState & ({
|
|
318
|
+
readonly returning: false;
|
|
319
|
+
} | {
|
|
320
|
+
readonly value: false;
|
|
321
|
+
});
|
|
322
|
+
/** State of a query of SQL text of one row, which `optional` applies to. */
|
|
323
|
+
type OneRowSqlQueryState = SqlQueryState & {
|
|
324
|
+
readonly returned: "one" | "nullable" | "optional";
|
|
325
|
+
};
|
|
326
|
+
/** State of a query of SQL text of one row that returns its number or its record, which `nullable` applies to. */
|
|
327
|
+
type OneRecordSqlQueryState = OneRowSqlQueryState & RecordSqlQueryState;
|
|
328
|
+
/** Record that the fields of a query of SQL text of state `S` add to: the fields selected earlier, or none. */
|
|
329
|
+
type ReturnedRecord<S extends SqlQueryState> = S["returning"] extends true ? S["result"] : Record<never, never>;
|
|
330
|
+
/** Record of fields `P` with the fields of `N` added, replacing the fields of their keys. */
|
|
331
|
+
type MergeFields<P, N> = { [K in keyof P | keyof N]: K extends keyof N ? N[K] : K extends keyof P ? P[K] : never; };
|
|
332
|
+
/** State of a query of SQL text of state `S` whose rows are in rows mode `Rows`. */
|
|
333
|
+
type RowsState<S extends SqlQueryState, Rows extends ResultRows> = ChangeSqlQueryState<S, {
|
|
334
|
+
returned: Rows;
|
|
335
|
+
rows: S["returning"] extends true ? Rows : "one";
|
|
336
|
+
}>;
|
|
337
|
+
/** State of a query of SQL text of state `S` that returns value `V` of each row in rows mode `Rows`. */
|
|
338
|
+
type ValueState<S extends SqlQueryState, V, Rows extends ResultRows> = ChangeSqlQueryState<S, {
|
|
339
|
+
result: V;
|
|
340
|
+
rows: Rows;
|
|
341
|
+
returned: Rows;
|
|
342
|
+
value: true;
|
|
343
|
+
returning: true;
|
|
344
|
+
}>;
|
|
345
|
+
/**
|
|
346
|
+
* Immutable query of a statement of SQL text, which executes on its database when awaited.
|
|
347
|
+
*
|
|
348
|
+
* Without a selection, it resolves to the number of the rows of the command tag of its statement, such as the rows that an `UPDATE` changes; `select`, `get`, and `pluck` return the fields of the rows of the statement instead, decoded by types.
|
|
349
|
+
*/
|
|
350
|
+
declare class SqlQuery<out S extends SqlQueryState> {
|
|
351
|
+
/** Compiles the statement of the query. */
|
|
352
|
+
private readonly source;
|
|
353
|
+
/** Database that executes the statement. */
|
|
354
|
+
private readonly database;
|
|
355
|
+
/** How the result of the statement is decoded. */
|
|
356
|
+
private readonly plan;
|
|
357
|
+
readonly types: S;
|
|
358
|
+
constructor(
|
|
359
|
+
/** Compiles the statement of the query. */
|
|
360
|
+
source: StatementSource,
|
|
361
|
+
/** Database that executes the statement. */
|
|
362
|
+
database: Pick<Database, "execute">,
|
|
363
|
+
/** How the result of the statement is decoded. */
|
|
364
|
+
plan: FlatResultPlan);
|
|
365
|
+
/** Executes the query on its database. */
|
|
366
|
+
then<R1 = SqlQueryResult<S>, R2 = never>(onFulfilled?: ((result: SqlQueryResult<S>) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
|
|
367
|
+
/**
|
|
368
|
+
* Returns the records of the rows of the statement instead of their number, with the values of the result columns named by the keys of `fields`, decoded by their types; it adds the fields to those selected earlier, replacing fields under their keys.
|
|
369
|
+
*
|
|
370
|
+
* A type of a column that can be `NULL` must be nullable.
|
|
371
|
+
* The statement rejects without a column of a field, or with the column twice; other columns are ignored.
|
|
372
|
+
*/
|
|
373
|
+
select<S extends RecordSqlQueryState, F extends FieldTypes>(this: SqlQuery<S>, fields: F): SqlQuery<ChangeSqlQueryState<S, {
|
|
374
|
+
result: MergeFields<ReturnedRecord<S>, DecodedFields<F>>;
|
|
375
|
+
rows: S["returned"];
|
|
376
|
+
value: false;
|
|
377
|
+
returning: true;
|
|
378
|
+
}>>;
|
|
379
|
+
/**
|
|
380
|
+
* Returns the value of the only column of the row of the statement instead of the number of the rows, decoded by `type`.
|
|
381
|
+
*
|
|
382
|
+
* Without a row, it rejects with `NotFoundError` unless `optional` makes the query resolve to `undefined`; it rejects several rows.
|
|
383
|
+
* A `NULL` value is `null`, so a type of a column that can be `NULL` must be nullable.
|
|
384
|
+
*/
|
|
385
|
+
get<S extends SqlQueryState, C extends AnyType>(this: SqlQuery<S>, type: C): SqlQuery<ValueState<S, TypeOutput<C>, OneValueRows<S["returned"]>>>;
|
|
386
|
+
/**
|
|
387
|
+
* Returns the values of the only column of the rows of the statement instead of their number, decoded by `type`, keeping whether the query returns an array or one value.
|
|
388
|
+
*
|
|
389
|
+
* A `NULL` value is `null`, so a type of a column that can be `NULL` must be nullable.
|
|
390
|
+
*/
|
|
391
|
+
pluck<S extends SqlQueryState, C extends AnyType>(this: SqlQuery<S>, type: C): SqlQuery<ValueState<S, TypeOutput<C>, ValueRows<S["returned"]>>>;
|
|
392
|
+
/**
|
|
393
|
+
* Returns the row of the statement instead of an array, and rejects with `NotFoundError` without it and with several rows; it adds no limit to the statement.
|
|
394
|
+
*
|
|
395
|
+
* Before a selection, the query resolves to the number of the rows, `1`, and rejects as well.
|
|
396
|
+
*/
|
|
397
|
+
take<S extends SqlQueryState>(this: SqlQuery<S>): SqlQuery<RowsState<S, OneRow<S["returned"]>>>;
|
|
398
|
+
/**
|
|
399
|
+
* Makes a query of one row, such as one of `take` or `get`, resolve to `undefined` without the row.
|
|
400
|
+
*
|
|
401
|
+
* Before a selection, the query resolves to `0` without the row.
|
|
402
|
+
*/
|
|
403
|
+
optional<S extends OneRowSqlQueryState>(this: SqlQuery<S>): SqlQuery<RowsState<S, "optional">>;
|
|
404
|
+
/**
|
|
405
|
+
* Makes a query of one record, such as one of `take`, resolve to `null` without the row.
|
|
406
|
+
*
|
|
407
|
+
* A value of `get` or `pluck` is never `null` for a missing row, which would read as a `NULL` value, so a query of values does not accept it.
|
|
408
|
+
* Before a selection, the query resolves to `0` without the row.
|
|
409
|
+
*/
|
|
410
|
+
nullable<S extends OneRecordSqlQueryState>(this: SqlQuery<S>): SqlQuery<RowsState<S, "nullable">>;
|
|
411
|
+
/** Compiles the query into SQL text and parameters, as it executes. */
|
|
412
|
+
toSQL(): SqlStatement;
|
|
413
|
+
/** Compiles the statement, executes it on the database, and decodes its result by the plan. */
|
|
414
|
+
private execute;
|
|
415
|
+
/** Creates the query of the same statement with result plan `plan`. */
|
|
416
|
+
private derive;
|
|
417
|
+
/** Creates the query of the same fields in rows mode `rows`. */
|
|
418
|
+
private deriveRows;
|
|
419
|
+
/** Creates the query that returns the value of the only column of each row in rows mode `rows`, decoded by `type` of `method`. */
|
|
420
|
+
private deriveValue;
|
|
421
|
+
/** Creates the query of one row in rows mode `rows`, rejecting a query of many rows. */
|
|
422
|
+
private changeOneRow;
|
|
423
|
+
}
|
|
424
|
+
/** Query of SQL text of any state. */
|
|
425
|
+
type AnySqlQuery = SqlQuery<any>;
|
|
426
|
+
/** Starts the query of the statement that `source` compiles, executed on `database`, which resolves to the number of the rows of its command tag. */
|
|
427
|
+
declare function startSqlQuery(source: StatementSource, database: Pick<Database, "execute">): SqlQuery<InitialSqlQueryState>;
|
|
428
|
+
export { OneRow as A, takeOnlyRow as B, renderFragment as C, bindParameter as D, assertUntypedValue as E, ResultRows as F, toValueRows as H, ValueRows as I, createFieldDecodeError as L, ResultByRows as M, ResultDecodeError as N, encodeParameter as O, ResultMode as P, createResultDecodeError as R, param as S, UntypedValue as T, toMissingResult as V, isDatabase as _, SqlQuery as a, SqlValue as b, StatementSource as c, DatabaseOptions as d, IsolationLevel as f, createDatabase as g, TransactionOptions as h, InitialSqlQueryState as i, OneValueRows as j, NotFoundError as k, startSqlQuery as l, SessionOptions as m, DecodedFields as n, SqlQueryResult as o, PollLockOptions as p, FieldTypes as r, SqlQueryState as s, AnySqlQuery as t, Database as u, ParameterBinder as v, sql as w, identifier as x, SqlFragment as y, isRecordKey as z };
|