1 | /// <reference types="node" />
|
2 | import { EventEmitter } from 'events';
|
3 | import { type Parameter, type DataType } from './data-type';
|
4 | import Connection from './connection';
|
5 | import { type Metadata } from './metadata-parser';
|
6 | import { SQLServerStatementColumnEncryptionSetting } from './always-encrypted/types';
|
7 | import { type ColumnMetadata } from './token/colmetadata-token-parser';
|
8 | import { Collation } from './collation';
|
9 | /**
|
10 | * The callback is called when the request has completed, either successfully or with an error.
|
11 | * If an error occurs during execution of the statement(s), then `err` will describe the error.
|
12 | *
|
13 | * As only one request at a time may be executed on a connection, another request should not
|
14 | * be initiated until this callback is called.
|
15 | *
|
16 | * This callback is called before `requestCompleted` is emitted.
|
17 | */
|
18 | type CompletionCallback =
|
19 | /**
|
20 | * @param error
|
21 | * If an error occurred, an error object.
|
22 | *
|
23 | * @param rowCount
|
24 | * The number of rows emitted as result of executing the SQL statement.
|
25 | *
|
26 | * @param rows
|
27 | * Rows as a result of executing the SQL statement.
|
28 | * Will only be available if [[ConnectionOptions.rowCollectionOnRequestCompletion]] is `true`.
|
29 | */
|
30 | (error: Error | null | undefined, rowCount?: number, rows?: any) => void;
|
31 | export interface ParameterOptions {
|
32 | output?: boolean;
|
33 | length?: number;
|
34 | precision?: number;
|
35 | scale?: number;
|
36 | }
|
37 | interface RequestOptions {
|
38 | statementColumnEncryptionSetting?: SQLServerStatementColumnEncryptionSetting;
|
39 | }
|
40 | /**
|
41 | * ```js
|
42 | * const { Request } = require('tedious');
|
43 | * const request = new Request("select 42, 'hello world'", (err, rowCount) {
|
44 | * // Request completion callback...
|
45 | * });
|
46 | * connection.execSql(request);
|
47 | * ```
|
48 | */
|
49 | declare class Request extends EventEmitter {
|
50 | /**
|
51 | * @private
|
52 | */
|
53 | sqlTextOrProcedure: string | undefined;
|
54 | /**
|
55 | * @private
|
56 | */
|
57 | parameters: Parameter[];
|
58 | /**
|
59 | * @private
|
60 | */
|
61 | parametersByName: {
|
62 | [key: string]: Parameter;
|
63 | };
|
64 | /**
|
65 | * @private
|
66 | */
|
67 | preparing: boolean;
|
68 | /**
|
69 | * @private
|
70 | */
|
71 | canceled: boolean;
|
72 | /**
|
73 | * @private
|
74 | */
|
75 | paused: boolean;
|
76 | /**
|
77 | * @private
|
78 | */
|
79 | userCallback: CompletionCallback;
|
80 | /**
|
81 | * @private
|
82 | */
|
83 | handle: number | undefined;
|
84 | /**
|
85 | * @private
|
86 | */
|
87 | error: Error | undefined;
|
88 | /**
|
89 | * @private
|
90 | */
|
91 | connection: Connection | undefined;
|
92 | /**
|
93 | * @private
|
94 | */
|
95 | timeout: number | undefined;
|
96 | /**
|
97 | * @private
|
98 | */
|
99 | rows?: Array<any>;
|
100 | /**
|
101 | * @private
|
102 | */
|
103 | rst?: Array<any>;
|
104 | /**
|
105 | * @private
|
106 | */
|
107 | rowCount?: number;
|
108 | /**
|
109 | * @private
|
110 | */
|
111 | callback: CompletionCallback;
|
112 | shouldHonorAE?: boolean;
|
113 | statementColumnEncryptionSetting: SQLServerStatementColumnEncryptionSetting;
|
114 | cryptoMetadataLoaded: boolean;
|
115 | /**
|
116 | * This event, describing result set columns, will be emitted before row
|
117 | * events are emitted. This event may be emitted multiple times when more
|
118 | * than one recordset is produced by the statement.
|
119 | *
|
120 | * An array like object, where the columns can be accessed either by index
|
121 | * or name. Columns with a name that is an integer are not accessible by name,
|
122 | * as it would be interpreted as an array index.
|
123 | */
|
124 | on(event: 'columnMetadata', listener: (columns: ColumnMetadata[] | {
|
125 | [key: string]: ColumnMetadata;
|
126 | }) => void): this;
|
127 | /**
|
128 | * The request has been prepared and can be used in subsequent calls to execute and unprepare.
|
129 | */
|
130 | on(event: 'prepared', listener: () => void): this;
|
131 | /**
|
132 | * The request encountered an error and has not been prepared.
|
133 | */
|
134 | on(event: 'error', listener: (err: Error) => void): this;
|
135 | /**
|
136 | * A row resulting from execution of the SQL statement.
|
137 | */
|
138 | on(event: 'row', listener:
|
139 | /**
|
140 | * An array or object (depends on [[ConnectionOptions.useColumnNames]]), where the columns can be accessed by index/name.
|
141 | * Each column has two properties, `metadata` and `value`:
|
142 | *
|
143 | * * `metadata`
|
144 | *
|
145 | * The same data that is exposed in the `columnMetadata` event.
|
146 | *
|
147 | * * `value`
|
148 | *
|
149 | * The column's value. It will be `null` for a `NULL`.
|
150 | * If there are multiple columns with the same name, then this will be an array of the values.
|
151 | */
|
152 | (columns: any) => void): this;
|
153 | /**
|
154 | * All rows from a result set have been provided (through `row` events).
|
155 | *
|
156 | * This token is used to indicate the completion of a SQL statement.
|
157 | * As multiple SQL statements can be sent to the server in a single SQL batch, multiple `done` can be generated.
|
158 | * An `done` event is emitted for each SQL statement in the SQL batch except variable declarations.
|
159 | * For execution of SQL statements within stored procedures, `doneProc` and `doneInProc` events are used in place of `done`.
|
160 | *
|
161 | * If you are using [[Connection.execSql]] then SQL server may treat the multiple calls with the same query as a stored procedure.
|
162 | * When this occurs, the `doneProc` and `doneInProc` events may be emitted instead. You must handle both events to ensure complete coverage.
|
163 | */
|
164 | on(event: 'done', listener:
|
165 | /**
|
166 | * @param rowCount
|
167 | * The number of result rows. May be `undefined` if not available.
|
168 | *
|
169 | * @param more
|
170 | * If there are more results to come (probably because multiple statements are being executed), then `true`.
|
171 | *
|
172 | * @param rst
|
173 | * Rows as a result of executing the SQL statement.
|
174 | * Will only be available if Connection's [[ConnectionOptions.rowCollectionOnDone]] is `true`.
|
175 | */
|
176 | (rowCount: number | undefined, more: boolean, rst?: any[]) => void): this;
|
177 | /**
|
178 | * `request.on('doneInProc', function (rowCount, more, rows) { });`
|
179 | *
|
180 | * Indicates the completion status of a SQL statement within a stored procedure. All rows from a statement
|
181 | * in a stored procedure have been provided (through `row` events).
|
182 | *
|
183 | * This event may also occur when executing multiple calls with the same query using [[execSql]].
|
184 | */
|
185 | on(event: 'doneInProc', listener:
|
186 | /**
|
187 | * @param rowCount
|
188 | * The number of result rows. May be `undefined` if not available.
|
189 | *
|
190 | * @param more
|
191 | * If there are more results to come (probably because multiple statements are being executed), then `true`.
|
192 | *
|
193 | * @param rst
|
194 | * Rows as a result of executing the SQL statement.
|
195 | * Will only be available if Connection's [[ConnectionOptions.rowCollectionOnDone]] is `true`.
|
196 | */
|
197 | (rowCount: number | undefined, more: boolean, rst?: any[]) => void): this;
|
198 | /**
|
199 | * Indicates the completion status of a stored procedure. This is also generated for stored procedures
|
200 | * executed through SQL statements.\
|
201 | * This event may also occur when executing multiple calls with the same query using [[execSql]].
|
202 | */
|
203 | on(event: 'doneProc', listener:
|
204 | /**
|
205 | * @param rowCount
|
206 | * The number of result rows. May be `undefined` if not available.
|
207 | *
|
208 | * @param more
|
209 | * If there are more results to come (probably because multiple statements are being executed), then `true`.
|
210 | *
|
211 | * @param rst
|
212 | * Rows as a result of executing the SQL statement.
|
213 | * Will only be available if Connection's [[ConnectionOptions.rowCollectionOnDone]] is `true`.
|
214 | */
|
215 | (rowCount: number | undefined, more: boolean, procReturnStatusValue: number, rst?: any[]) => void): this;
|
216 | /**
|
217 | * A value for an output parameter (that was added to the request with [[addOutputParameter]]).
|
218 | * See also `Using Parameters`.
|
219 | */
|
220 | on(event: 'returnValue', listener:
|
221 | /**
|
222 | * @param parameterName
|
223 | * The parameter name. (Does not start with '@'.)
|
224 | *
|
225 | * @param value
|
226 | * The parameter's output value.
|
227 | *
|
228 | * @param metadata
|
229 | * The same data that is exposed in the `columnMetaData` event.
|
230 | */
|
231 | (parameterName: string, value: unknown, metadata: Metadata) => void): this;
|
232 | /**
|
233 | * This event gives the columns by which data is ordered, if `ORDER BY` clause is executed in SQL Server.
|
234 | */
|
235 | on(event: 'order', listener:
|
236 | /**
|
237 | * @param orderColumns
|
238 | * An array of column numbers in the result set by which data is ordered.
|
239 | */
|
240 | (orderColumns: number[]) => void): this;
|
241 | on(event: 'requestCompleted', listener: () => void): this;
|
242 | on(event: 'cancel', listener: () => void): this;
|
243 | on(event: 'pause', listener: () => void): this;
|
244 | on(event: 'resume', listener: () => void): this;
|
245 | /**
|
246 | * @private
|
247 | */
|
248 | emit(event: 'columnMetadata', columns: ColumnMetadata[] | {
|
249 | [key: string]: ColumnMetadata;
|
250 | }): boolean;
|
251 | /**
|
252 | * @private
|
253 | */
|
254 | emit(event: 'prepared'): boolean;
|
255 | /**
|
256 | * @private
|
257 | */
|
258 | emit(event: 'error', err: Error): boolean;
|
259 | /**
|
260 | * @private
|
261 | */
|
262 | emit(event: 'row', columns: any): boolean;
|
263 | /**
|
264 | * @private
|
265 | */
|
266 | emit(event: 'done', rowCount: number | undefined, more: boolean, rst?: any[]): boolean;
|
267 | /**
|
268 | * @private
|
269 | */
|
270 | emit(event: 'doneInProc', rowCount: number | undefined, more: boolean, rst?: any[]): boolean;
|
271 | /**
|
272 | * @private
|
273 | */
|
274 | emit(event: 'doneProc', rowCount: number | undefined, more: boolean, procReturnStatusValue: number, rst?: any[]): boolean;
|
275 | /**
|
276 | * @private
|
277 | */
|
278 | emit(event: 'returnValue', parameterName: string, value: unknown, metadata: Metadata): boolean;
|
279 | /**
|
280 | * @private
|
281 | */
|
282 | emit(event: 'requestCompleted'): boolean;
|
283 | /**
|
284 | * @private
|
285 | */
|
286 | emit(event: 'cancel'): boolean;
|
287 | /**
|
288 | * @private
|
289 | */
|
290 | emit(event: 'pause'): boolean;
|
291 | /**
|
292 | * @private
|
293 | */
|
294 | emit(event: 'resume'): boolean;
|
295 | /**
|
296 | * @private
|
297 | */
|
298 | emit(event: 'order', orderColumns: number[]): boolean;
|
299 | /**
|
300 | * @param sqlTextOrProcedure
|
301 | * The SQL statement to be executed
|
302 | *
|
303 | * @param callback
|
304 | * The callback to execute once the request has been fully completed.
|
305 | */
|
306 | constructor(sqlTextOrProcedure: string | undefined, callback: CompletionCallback, options?: RequestOptions);
|
307 | /**
|
308 | * @param name
|
309 | * The parameter name. This should correspond to a parameter in the SQL,
|
310 | * or a parameter that a called procedure expects. The name should not start with `@`.
|
311 | *
|
312 | * @param type
|
313 | * One of the supported data types.
|
314 | *
|
315 | * @param value
|
316 | * The value that the parameter is to be given. The Javascript type of the
|
317 | * argument should match that documented for data types.
|
318 | *
|
319 | * @param options
|
320 | * Additional type options. Optional.
|
321 | */
|
322 | addParameter(name: string, type: DataType, value?: unknown, options?: Readonly<ParameterOptions> | null): void;
|
323 | /**
|
324 | * @param name
|
325 | * The parameter name. This should correspond to a parameter in the SQL,
|
326 | * or a parameter that a called procedure expects.
|
327 | *
|
328 | * @param type
|
329 | * One of the supported data types.
|
330 | *
|
331 | * @param value
|
332 | * The value that the parameter is to be given. The Javascript type of the
|
333 | * argument should match that documented for data types
|
334 | *
|
335 | * @param options
|
336 | * Additional type options. Optional.
|
337 | */
|
338 | addOutputParameter(name: string, type: DataType, value?: unknown, options?: Readonly<ParameterOptions> | null): void;
|
339 | /**
|
340 | * @private
|
341 | */
|
342 | makeParamsParameter(parameters: Parameter[]): string;
|
343 | /**
|
344 | * @private
|
345 | */
|
346 | validateParameters(collation: Collation | undefined): void;
|
347 | /**
|
348 | * Temporarily suspends the flow of data from the database. No more `row` events will be emitted until [[resume] is called.
|
349 | * If this request is already in a paused state, calling [[pause]] has no effect.
|
350 | */
|
351 | pause(): void;
|
352 | /**
|
353 | * Resumes the flow of data from the database.
|
354 | * If this request is not in a paused state, calling [[resume]] has no effect.
|
355 | */
|
356 | resume(): void;
|
357 | /**
|
358 | * Cancels a request while waiting for a server response.
|
359 | */
|
360 | cancel(): void;
|
361 | /**
|
362 | * Sets a timeout for this request.
|
363 | *
|
364 | * @param timeout
|
365 | * The number of milliseconds before the request is considered failed,
|
366 | * or `0` for no timeout. When no timeout is set for the request,
|
367 | * the [[ConnectionOptions.requestTimeout]] of the [[Connection]] is used.
|
368 | */
|
369 | setTimeout(timeout?: number): void;
|
370 | }
|
371 | export default Request;
|