UNPKG

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